本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 實作 Chef 11.10 堆疊的配方
<a name="workingcookbook-chef11-10"></a>

**重要**  
 AWS OpsWorks Stacks 此服務已於 2024 年 5 月 26 日終止，並已針對新客戶和現有客戶停用。我們強烈建議客戶盡快將其工作負載遷移至其他解決方案。如果您對遷移有任何疑問，請透過 [AWS re：Post](https://repost.aws/) 或透過 [AWS Premium Support](https://aws.amazon.com/support) 聯絡 AWS 支援 團隊。

Chef 11.10 堆疊與 Chef 11.4 堆疊相比有下列優點：
+ Chef 執行使用 Ruby 2.0.0，因此您的配方可以使用新的 Ruby 語法。
+ 配方可以使用 Chef search 和資料包。

  Chef 11.10 堆疊可以使用許多社群技術指南，而無須修改。
+ 您可以使用 Berkshelf 來管理技術指南。

  Berkshelf 提供更多更靈活的方式來管理您的自訂技術指南，以及在堆疊中使用社群技術指南。
+ 技術指南必須在 `metadata.rb` 中宣告依存項目。

  若您的技術指南依存於其他技術指南，您必須在您技術指南的 `metadata.rb` 檔案中包含該依存項目。例如，若您的技術指南包含具有如 `include_recipe anothercookbook::somerecipe` 陳述式的配方，則您技術指南的 `metadata.rb` 檔案就必須包含下列內容：`depends "anothercookbook"`。
+ OpsWorks 只有在堆疊包含 MySQL layer 時， Stacks 才會在堆疊的執行個體上安裝 MySQL 用戶端。
+ OpsWorks 只有在堆疊包含 Ganglia 層時， Stacks 才會在堆疊的執行個體上安裝 Ganglia 用戶端。
+ 若部署執行 `bundle install` 但安裝失敗，部署也會失敗。

**重要**  
請勿針對自訂或社群技術指南重複使用內建技術指南的名稱。和內建技術指南具有相同名稱的自訂技術指南可能會失敗。如需 Chef 11.10、11.4 和 0.9 堆疊可用內建技術指南的完整清單，請參閱 [GitHub 上的 opsworks-cookbooks 儲存庫](https://github.com/aws/opsworks-cookbooks)。  
帶有非 ASCII 字元並在 Chef 0.9 和 11.4 堆疊上可成功執行的技術指南，在 Chef 11.10 堆疊上可能會失敗。原因是 Chef 11.10 堆疊會針對 Chef run 使用 Ruby 2.0.0，該版本比 Ruby 1.8.7 具有更嚴格的編碼規範。為了確保這類技術指南能在 Chef 11.10 堆疊上成功執行，每個使用非 ASCII 字元的檔案都應在其頂端具備註解，提供關於編碼的提示。例如，針對 UTF-8 編碼，註解應為 `# encoding: UTF-8`。如需 Ruby 2.0.0 編碼的詳細資訊，請參閱 [Encoding](http://www.ruby-doc.org/core-2.0.0/Encoding.html)。

**Topics**
+ [技術指南安裝與優先順序](#workingcookbook-chef11-10-override)
+ [使用 Chef 搜尋](#workingcookbook-chef11-10-search)
+ [使用資料包](#workingcookbook-chef11-10-databag)
+ [使用 Berkshelf](#workingcookbook-chef11-10-berkshelf)

## 技術指南安裝與優先順序
<a name="workingcookbook-chef11-10-override"></a>

安裝 OpsWorks Stacks 技術指南的程序對 Chef 11.10 堆疊的運作方式與舊版 Chef 略有不同。對於 Chef 11.10 堆疊，在 OpsWorks Stacks 安裝內建、自訂和 Berkshelf 技術指南之後，它會以下列順序將它們合併到通用目錄：

1. 內建技術指南。

1. Berkshelf 技術指南 (若有的話)。

1. 自訂技術指南 (若有的話)。

當 OpsWorks Stacks 執行此合併時，它會複製目錄的完整內容，包括配方。若有任何重複項目，則會套用下列規則：
+ Berkshelf 技術指南的內容會優先於內建技術指南。
+ 自訂技術指南的內容會優先於 Berkshelf 技術指南。

為了示範此程序運作的方式，請考慮以下案例，其中三個技術指南目錄都包含名為 `mycookbook` 的技術指南：
+ 內建技術指南 – `mycookbook`包含名為 的屬性檔案`someattributes.rb`、名為 的範本檔案`sometemplate.erb`，以及名為 的配方`somerecipe.rb`。
+ Berkshelf 技術指南 – `mycookbook`包括 `sometemplate.erb`和 `somerecipe.rb`。
+ 自訂技術指南 – `mycookbook`包含 `somerecipe.rb`。

合併的技術指南包含以下內容：
+ 來自內建技術指南的 `someattributes.rb`。
+ 來自 Berkshelf 技術指南的 `sometemplate.erb`。
+ 來自自訂技術指南的 `somerecipe.rb`。

**重要**  
建議您不要透過將整個內建技術指南複製到您的儲存庫，然後修改技術指南的一部分，來自訂您的 Chef 11.10 堆疊。這樣做會覆寫整個內建技術指南 (包含配方)。如果 OpsWorks Stacks 更新了該技術指南，除非您手動更新私有複本，否則您的堆疊將不會受益於這些更新。如需如何自訂堆疊的詳細資訊，請參閱[自訂 OpsWorks Stacks](customizing.md)。

## 使用 Chef 搜尋
<a name="workingcookbook-chef11-10-search"></a>

您可以在您的配方中使用 Chef [`search` 方法](http://docs.chef.io/dsl_recipe.html#search)來查詢堆疊資料。您可以使用與 Chef 伺服器相同的語法，但 OpsWorks Stacks 會從本機節點物件取得資料，而不是查詢 Chef 伺服器。此資料包括：
+ 執行個體的[堆疊組態及部署屬性](workingstacks-json.md)。
+ 執行個體的內建和自訂技術指南之屬性檔案的屬性。
+ 由 Ohai 收集的系統資料。

堆疊組態和部署屬性包含配方通常透過搜尋取得的大部分資訊，包括堆疊中每個線上執行個體的主機名稱和 IP 地址等資料。 OpsWorks 堆疊會為每個[生命週期事件](workingcookbook-events.md)更新這些屬性，以確保它們準確反映目前的堆疊狀態。這表示您通常可以在您的堆疊中使用搜尋依存的社群配方，而無須修改。search 方法仍然會傳回適當的資料，只是該資料會來自堆疊組態及部署屬性，而非伺服器。

 OpsWorks Stacks 搜尋的主要限制是僅處理本機節點物件中的資料，特別是堆疊組態和部署屬性。因此，下列資料類型可能無法透過 search 取得：
+ 在其他執行個體上的本機定義屬性。

  如果配方在本機定義 屬性，該資訊不會回報給 OpsWorks Stacks 服務，因此您無法使用搜尋從其他執行個體存取該資料。
+ 自訂 `deploy` 屬性。

  您可以在您[部署應用程式](workingapps-deploying.md)時指定自訂 JSON，對應的屬性即會為該部署安裝在堆疊的執行個體上。但是，若您僅部署到選取的執行個體，屬性也會在那些執行個體上安裝。在所有其他執行個體上查詢那些自訂 JSON 屬性都會失敗。此外，自訂屬性也僅會包含在該特定部署的堆疊組態和部署 JSON 中。您僅能在下一次生命週期事件安裝新的一組堆疊組態及部署屬性之前存取他們。請注意，若您[指定堆疊的自訂 JSON](workingstacks-json.md)，屬性便會針對每個生命週期事件於每個執行個體上安裝，並且永遠可透過 search 進行存取。
+ 來自其他執行個體的 Ohai 資料。

  Chef 的 [Ohai 工具](http://docs.chef.io/resource_ohai.html)會取得執行個體上的各種系統資料，並新增到節點物件。這項資料會存放於本機，而不會報告回 OpsWorks Stacks 服務，因此 search 無法從其他執行個體存取 Ohai 資料。但是，這項資料的其中一部分可能會包含在堆疊組態及部署屬性中。
+ 離線執行個體。

  堆疊組態及部署屬性只包含線上執行個體的資料。

下列配方摘要會示範如何使用 search 取得 PHP layer 執行個體的私有 IP 地址。

```
appserver = search(:node, "role:php-app").first
Chef::Log.info("The private IP is '#{appserver[:private_ip]}'")
```

**注意**  
當 OpsWorks Stacks 將堆疊組態和部署屬性新增至節點物件時，它實際上會建立兩組 layer 屬性，每個屬性都具有相同的資料。`layers` 命名空間中有一個集合，這是 Stacks OpsWorks 存放資料的方式。另一組則位於 `role` 命名空間，即 Chef 伺服器存放對等資料的方式。`role` 命名空間的目的是允許為 Chef 伺服器實作的搜尋程式碼在 Stacks OpsWorks 執行個體上執行。如果您專門為 OpsWorks Stacks 編寫程式碼，您可以在上述範例中使用 `layers:php-app`或 `role:php-app` `search`，並傳回相同的結果。

## 使用資料包
<a name="workingcookbook-chef11-10-databag"></a>

您可以在您的配方中使用 Chef [`data_bag_item` 方法](http://docs.chef.io/dsl_recipe.html#data-bag-item)來查詢資料包中的資訊。您會使用與您在使用 Chef 伺服器時相同的語法，但 OpsWorks Stacks 會從執行個體的堆疊組態及部署屬性取得資料。不過， OpsWorks Stacks 目前不支援 Chef 環境，因此 `node.chef_environment` 一律會傳回 `_default`。

您會透過使用自訂 JSON 建立資料包，來將一或多個屬性新增至 `[:opsworks][:data_bags]` 屬性。以下範例示範在自訂 JSON 中建立資料包的一般格式。

**注意**  
您無法透過將其新增至您的技術指南儲存庫，來建立資料包。您必須使用自訂 JSON。

```
{
  "opsworks": {
    "data_bags": {
      "bag_name1": {
        "item_name1: {
          "key1" : “value1”,
          "key2" : “value2”,
          ...
        }
      },
      "bag_name2": {
        "item_name1": {
          "key1" : “value1”,
          "key2" : “value2”,
          ...
        }
      },
      ...
    }
  }
}
```

您通常會[指定堆疊的自訂 JSON](workingstacks-json.md)，針對每個接下來的生命週期事件，於每個執行個體上安裝自訂屬性。您也可以在您部署應用程式時指定自訂 JSON，但那些屬性只會針對該部署進行安裝，並且可能只會安裝到選取的執行個體。如需詳細資訊，請參閱[部署應用程式](workingapps-deploying.md)。

下列自訂 JSON 範例會建立名為 `myapp` 的資料包。其中有一個項目 (`mysql`)，以及兩個鍵/值對。

```
{ "opsworks": {
    "data_bags": {
      "myapp": {
        "mysql": { 
          "username": "default-user",
          "password": "default-pass"
        }
      }
    }
  }
}
```

若要在您的配方中使用資料，您可以呼叫 `data_bag_item` 並將資料包和值名稱傳遞給它，如下列摘要所示。

```
mything = data_bag_item("myapp", "mysql")
Chef::Log.info("The username is '#{mything['username']}' ")
```

若要修改資料包中的資料，您只需修改自訂 JSON，它便會針對下一次的生命週期事件安裝在堆疊的執行個體上。

## 使用 Berkshelf
<a name="workingcookbook-chef11-10-berkshelf"></a>

在 Chef 0.9 和 Chef 11.4 堆疊中，您只能安裝一個自訂技術指南儲存庫。在 Chef 11.10 堆疊中，您可以使用 [Berkshelf](http://berkshelf.com/) 來管理您的技術指南和其依存項目，讓您可以從多個儲存庫安裝技術指南。(如需詳細資訊，請參閱 [本機封裝技術指南依存性](best-practices-packaging-cookbooks-locally.md)。) 特別是，使用 Berkshelf，您可以直接從儲存庫安裝 OpsWorks 與 Stacks 相容的社群技術指南，而不必將其複製到自訂技術指南儲存庫。支援的 Berkshelf 版本取決於作業系統。如需詳細資訊，請參閱[OpsWorks Stacks 作業系統](workinginstances-os.md)。

若要使用 Berkshelf，您必須明確啟用它，如[安裝自訂技術指南](workingcookbook-installingcustom-enable.md)中所說明。然後，在您的技術指南儲存庫根目錄中包含一個 `Berksfile` 檔案，指定要安裝的技術指南。

若要在 Berksfile 中指定外部技術指南來源，請在檔案的頂端包含一個來源屬性，指定預設儲存庫 URL。Berkshelf 會在來源 URL 中尋找技術指南，除非您明確指定儲存庫。然後，在每個您希望安裝的技術指南中包含一行文字，格式如下：

```
cookbook 'cookbook_name', ['>= cookbook_version'], [cookbook_options]
```

`cookbook` 之後的欄位會指定特定技術指南。
+ *cookbook\$1name* – （必要） 指定技術指南的名稱。

  若您沒有包含任何其他欄位，Berkshelf 會從指定來源 URL 安裝技術指南。
+ *cookbook\$1version* – （選用） 指定技術指南版本。

  您可以使用像是 `=` 或 `>=` 等前綴，來指定特定版本或可接受的版本範圍。若您並未指定版本，Berkshelf 會安裝最新的版本。
+ *cookbook\$1options* – （選用） 最後一個欄位是包含一或多個索引鍵/值對的雜湊，指定儲存庫位置等選項。

  例如，您可以包含一個 `git` 鍵，指定特定的 Git 儲存庫，以及一個 `tag` 鍵，指定特定的儲存庫分支。指定儲存庫分支通常是確保安裝您偏好之技術指南的最佳方式。

**重要**  
請不要透過在您的 Berksfile 中包含 `metadata` 並在 `metadata.rb` 中宣告技術指南依存項目，來宣告技術指南。若要使其正常執行，兩個檔案都必須位於相同的目錄中。使用 OpsWorks Stacks 時，Berksfile 必須位於儲存庫的根目錄中，但`metadata.rb`檔案必須位於各自的技術指南目錄中。您應改為在 Berksfile 中明確宣告外部技術指南。

以下為 Berksfile 的範例，示範指定技術指南的不同方式。如需如何建立 Berksfile 的詳細資訊，請參閱 [Berkshelf](http://berkshelf.com/)。

```
source "https://supermarket.chef.io"

cookbook 'apt'
cookbook 'bluepill', '>= 2.3.1'
cookbook 'ark', git: 'git://github.com/opscode-cookbooks/ark.git'
cookbook 'build-essential', '>= 1.4.2', git: 'git://github.com/opscode-cookbooks/build-essential.git', tag: 'v1.4.2'
```

此檔案會安裝以下技術指南：
+ 來自社群技術指南儲存庫的最新版本 `apt`。
+ 來自社群技術指南的最新版本 `bluepill` (只要其版本為 2.3.1 或更新版本)。
+ 來自指定儲存庫的最新版本 `ark`。

  此範例的 URL 為 GitHub 上公有社群技術指南儲存庫的 URL，但您可以從其他儲存庫安裝技術指南，包含私有儲存庫。如需詳細資訊，請參閱 [Berkshelf](http://berkshelf.com/)。
+ 來自指定儲存庫 v1.4.2 分支的 `build-essential` 技術指南。

除了 Berksfile，自訂技術指南儲存庫可以包含自訂技術指南。在這種情況下， OpsWorks Stacks 會安裝兩組技術指南，這表示執行個體最多可以有三個技術指南儲存庫。
+ 內建的技術指南會安裝到 `/opt/aws/opsworks/current/cookbooks`。
+ 或您的自訂技術指南儲存庫包含技術指南，他們會安裝到 `/opt/aws/opsworks/current/site-cookbooks`。
+ 若您已啟用 Berkshelf，且您的自訂技術指南儲存庫包含 Berksfile，指定的技術指南便會安裝到 `/opt/aws/opsworks/current/berkshelf-cookbooks`。

內建技術指南和您的自訂技術指南會在設定期間安裝在每個執行個體上，除非您手動執行[**更新自訂技術指南**堆疊命令](workingstacks-commands.md)，否則後續不會更新。 OpsWorks 堆疊`berks install`會在每次 Chef 執行時執行，因此您的 Berkshelf 技術指南會根據下列規則，針對每個[生命週期事件](workingcookbook-events.md)更新：
+ 若您在儲存庫中有新的技術指南版本，此操作會從儲存庫更新技術指南。
+ 否則，此操作會從本機快取更新 Berkshelf 技術指南。

**注意**  
操作會覆寫 Berkshelf 技術指南，因此若您已修改任何技術指南的本機複本，變更將會遭到覆寫。如需詳細資訊，請參閱 [Berkshelf](http://berkshelf.com/)

您也可以透過執行**更新自訂技術指南**堆疊命令來更新您的 Berkshelf 技術指南，該命令會同時更新 Berkshelf 技術指南和您的自訂技術指南。