起動テンプレートのサポート - Amazon EKS

起動テンプレートのサポート

マネージド型ノードグループは、常に Amazon EC 2 Auto Scaling グループで使用する起動テンプレートでデプロイされます。Amazon EKS API は、ユーザーが指定したテンプレートをコピーするか、アカウントのデフォルト値で自動的に作成することにより、この起動テンプレートを作成します。自分の起動テンプレートとカスタム AMI を使用することで、マネージド型ノードをデプロイでき、最高レベルのカスタマイズを実現できます。自動生成された起動テンプレートを変更することは推奨しません。したがって、柔軟性を高めたい場合は、最初にマネージド型ノードグループを作成するときにカスタム起動テンプレートを指定するようにしてください。

自分の起動テンプレートを使用してマネージド型ノードグループをデプロイした後は、同じ起動テンプレートの異なるバージョンとして更新してください。ノードグループを別のバージョンの起動テンプレートに更新すると、指定した起動テンプレートバージョンの新しい設定と一致するように、グループ内のすべてのノードがリサイクルされます。カスタム起動テンプレートを使用していない既存のノードグループは、直接更新できません。むしろカスタム起動テンプレートを使用して、新しいノードグループを作成する必要があります。

起動テンプレート設定の基本

AWS Management Console、AWS CLI、または AWS を使用して、Amazon EC2 Auto Scaling 起動テンプレートを作成できます。詳細については、「Amazon EC2 Auto Scaling ユーザーガイド」の「Auto Scaling グループの起動テンプレートを作成する」を参照してください。起動テンプレートの一部の設定は、マネージド型ノードで使われている設定と似ています。起動テンプレートを使用してノードグループをデプロイまたは更新する場合、一部の設定はノードグループ設定または起動テンプレートのいずれかで指定する必要があります。両方の場所を指定しないでください。存在してはいけない場所に設定が存在する場合、ノードグループの作成や更新などの操作は失敗します。

次の表に、起動テンプレートで禁止されている設定を示します。また、マネージド型ノードグループの設定に必要な同様の設定がある場合は、その設定も示します。リスト化されている設定は、コンソールに表示される設定です。AWS CLI と SDK では、類似するが異なる名前が場合があります。

起動テンプレート — 禁止 Amazon EKS ノードグループ設定
[高度な詳細] の下の [IAM インスタンスプロファイル] [Configure Node group] (ノードグループを設定) ページの [Node group configuration] (ノードグループ設定) の下の [Node IAM role] (ノード IAM ロール)
[ネットワークインターフェイス] ([ネットワークインターフェイスを追加]) の下の [サブネット] [Specify networking] (ネットワーキングを指定) ページの [Node group network configuration] (ノードグループのネットワーク設定) の下の [Subnets] (サブネット)
[高度な詳細] の下の [シャットダウン動作] および [停止 – 休止動作]。起動テンプレートのどちらの設定でも、[起動テンプレート設定に含めない] のデフォルトを保持します。 同等のものはありません。Amazon EKS は、Auto Scaling グループではなく、インスタンスのライフサイクルを管理する必要があります。

次の表に、マネージド型ノードグループ構成で禁止される設定を示します。また、起動テンプレートで必要な同様の設定がある場合は、その設定も示します。リスト化されている設定は、コンソールに表示される設定です。AWS CLI と SDK とで名前が似ている場合があります。

Amazon EKS ノードグループ設定 — 禁止 起動テンプレート

(起動テンプレートでカスタム AMI を指定した場合のみ) [Set compute and scaling configuration] (コンピューティングとスケーリングの設定を実行) ページの [Node Group compute configuration] (ノードグループのコンピューティング設定) の下の [AMI type] (AMI タイプ) — [Specified in launch template] (起動テンプレートで指定) と、指定した AMI ID がコンソールに表示されます。

起動テンプレートで AMI タイプが指定されていない場合は、ノードグループ設定で AMI を選択できます。

[起動テンプレートのコンテンツ] での [AMI] – 次のいずれかの要件がある場合は、ID を指定する必要があります。

[Set compute and scaling configuration] (コンピューティングとスケーリングの設定を実行) ページの [Node Group compute configuration] (ノードグループのコンピューティング設定) の下の [Disk size] (ディスクサイズ) — [Specified in launch template] (起動テンプレートで指定) がコンソールに表示されます。 [ストレージ (ボリューム)] ([新しいボリュームの追加]) の下の [サイズ]。これを起動テンプレートで指定する必要があります。
[Specify Networking] (ネットワーキングを指定) ページの [Node group configuration] (ノードグループ設定) の下の [SSH key pair] (SSH キーペア) — コンソールに起動テンプレートで指定したキーまたは [Not specified in launch template] (起動テンプレートで指定されていません) が表示されます。 [キーペア (ログイン)] の下の [キーペア名]。
起動テンプレートを使用する場合は、リモートアクセスを許可するソースセキュリティグループを指定できません。 インスタンスの場合、[ネットワーク設定] の下の [セキュリティグループ]、または [ネットワークインターフェイス] ([ネットワークインターフェイスを追加])の下の [セキュリティグループ]。両方設定することはできません。詳細については、「カスタムセキュリティグループを使用する」を参照してください。
注記
  • 起動テンプレートを使用してノードグループをデプロイする場合は、起動テンプレート内の [起動テンプレートのコンテンツ] で 0 または 1 の [インスタンスタイプ] を指定します。または、コンソールの [コンピューティングとスケーリングの構成を設定する] ページにある [インスタンスタイプ] で 0 から 20 までのインスタンスタイプを指定できます。または、Amazon EKS API を使用する他のツールを使用して行うこともできます。起動テンプレートでインスタンスタイプを指定し、その起動テンプレートを使用してノードグループをデプロイする場合、コンソールや、Amazon EKS API を使用する他のツールを使用してインスタンスタイプを指定することはできません。起動テンプレートやコンソール、または Amazon EKS API を使用する他のツールを使用してインスタンスタイプを指定しない場合は、t3.medium インスタンスタイプが使用されます。ノードグループがスポットキャパシティータイプを使用している場合は、コンソールを使用して複数のインスタンスタイプを指定することをお勧めします。詳細については、「マネージド型ノードグループのキャパシティータイプ」を参照してください。

  • ノードグループにデプロイするコンテナが、インスタンスメタデータサービスバージョン 2 を使用している場合は、起動テンプレートの [メタデータレスポンスのホップ制限]2 に設定してください。詳細については、「Amazon EC2 User Guide for Linux Instances」(Linux インスタンス用 Amazon EC2 ユーザーガイド) の「Instance metadata and user data」(インスタンスメタデータとユーザーデータ) を参照してください。カスタム起動テンプレートを使用せずにマネージド型ノードグループをデプロイする場合、この値はデフォルトの起動テンプレートのノードグループに対して自動的に設定されます。

Amazon EC2 インスタンスへのタグ付け

起動テンプレートの TagSpecification パラメータを使用して、ノードグループの Amazon EC2 インスタンスに適用するタグを指定します。CreateNodegroup または UpdateNodegroupVersion API を呼び出す IAM エンティティには、ec2:RunInstances および ec2:CreateTags へのアクセス許可が必要です。また、起動テンプレートにタグが追加される必要があります。

カスタムセキュリティグループを使用する

起動テンプレートでカスタムの Amazon EC2 セキュリティグループを指定し、ノードグループ内のインスタンスに適用できます。これは、インスタンスレベルのセキュリティグループのパラメータ内か、ネットワークインターフェイス設定のパラメータの一部として指定できます。しかし、インスタンスレベルとネットワークインタフェイス、両方のセキュリティグループを指定して、起動テンプレートを作成することはできません。マネージドノード型グループでカスタムセキュリティグループを使用する際に適用される、次の条件を考慮してください。

  • Amazon EKS では、単一のネットワークインターフェイス仕様の起動テンプレートのみ使用できます。

  • デフォルトでは、Amazon EKS はクラスターセキュリティグループをノードグループ内のインスタンスに追加して、ノードとコントロールプレーンとの間の通信を容易にします。前述のいずれかのオプションを使用して、起動テンプレートでカスタムセキュリティグループを指定した場合、Amazon EKS はクラスターセキュリティグループを追加しません。したがって、セキュリティグループのインバウンドルールとアウトバウンドルールで、クラスターのエンドポイントとの通信が有効になっていることを確認する必要があります。セキュリティグループのルールが正しくない場合、ワーカーノードはクラスターに参加できません。セキュリティグループルールの詳細については、Amazon EKS セキュリティグループの要件および考慮事項を参照してください。

  • ノードグループ内のインスタンスへの SSH アクセスが必要な場合は、そのアクセスを許可するセキュリティグループを含めてください。

Amazon EC2 ユーザーデータ

起動テンプレートには、カスタムユーザーデータのセクションが含まれています。このセクションでは、個々のカスタム AMI を手動で作成しなくても、ノードグループの構成設定を指定できます。Bottlerocket で使用できる設定の詳細については、「GitHub」の「Using user data」(ユーザーデータの使用) を参照してください。

cloud-init を使用すると、インスタンス起動時に起動テンプレート内の Amazon EC2 ユーザーデータを提供できます。詳細については、「cloud-init ドキュメント」を参照してください。ユーザーデータを使用すると、一般的な設定操作を実行できます。これには、次の操作が含まれます。

マネージド型ノードグループで使用される起動テンプレートの Amazon EC2 ユーザーデータは、Amazon Linux AMI の場合 MIME マルチパートアーカイブ、Bottlerocket AMI の場合 TOML の形式である必要があります。これは、ユーザーデータが、ノードがクラスターに参加するために必要な Amazon EKS ユーザーデータにマージされるためです。kubelet を起動または変更するコマンドをユーザーデータに指定しないでください。これは Amazon EKS によってマージされたユーザーデータの一部として実行されます。ノードへのラベル設定などの一部の kubelet パラメータは、マネージド型ノードグループ API 経由で直接設定できます。

注記

手動での起動や、カスタムの設定パラメータの受け渡しなど、高度な kubelet のカスタマイズについては、AMI を指定するを参照してください。起動テンプレートでカスタム AMI ID が指定されている場合、Amazon EKS はユーザーデータをマージしません。

次の詳細では、Amazon Linux または Bottlerocket のユーザーデータセクションについて詳しく説明しています。

Amazon Linux user data

複数のユーザーデータブロックと単一の MIME マルチパートファイルを組み合わせることができます。例えば、カスタムパッケージをインストールするユーザーデータのシェルスクリプトを、Docker デーモンを設定するクラウドブートフックに組み合わせることができます。MIME マルチパートファイルには次のコンポーネントが含まれます。

  • コンテンツタイプとパートバウンダリの宣言: Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="

  • MIME バージョンの宣言: MIME-Version: 1.0

  • 次のコンポーネントを含む 1 つ以上のユーザーデータブロック:

    • ユーザーデータブロックの始まりを示す開始境界:--==MYBOUNDARY==

    • ブロックのコンテンツの種類の宣言: Content-Type: text/cloud-config; charset="us-ascii"。コンテンツタイプの詳細については、cloud-init のドキュメントを参照してください。

    • ユーザーデータのコンテンツ (例えば、シェルコマンドや cloud-init ディレクティブのリスト)。

    • MIME マルチパートファイルの終わりを示す、終了境界: --==MYBOUNDARY==--

    自分で MIME マルチパートファイルを作成するときに使用できる例は、次の通りです。

    MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="==MYBOUNDARY==" --==MYBOUNDARY== Content-Type: text/x-shellscript; charset="us-ascii" #!/bin/bash echo "Running custom user data script" --==MYBOUNDARY==--
Bottlerocket user data

Bottlerocket では、ユーザーデータは TOML 形式で構造化されています。Amazon EKS が提供するユーザーデータとマージするユーザーデータを提供できます。たとえば、追加の kubelet 設定を指定できます。

[settings.kubernetes.system-reserved] cpu = "10m" memory = "100Mi" ephemeral-storage= "1Gi"

サポートされる設定について詳しくは、「Bottlerocket ドキュメント」を参照してください。ユーザーデータにノードラベルとテイントを設定できます。ただし、代わりにノードグループ内にこれらを設定することをお勧めします。この場合、Amazon EKS によりこれらの設定が適用されます。

ユーザーデータをマージしても、書式設定は保持されませんが、コンテンツは同じままです。ユーザーデータに指定した設定は、Amazon EKS によって構成された設定よりも優先されます。したがって、settings.kubernetes.max-pods または settings.kubernetes.cluster-dns-ip を設定した場合、ユーザーデータの値がノードに適用されます。

Amazon EKS で、有効な TOML がすべてサポートされるわけではありません。以下は、サポートされていない既知の形式の一覧です。

  • 引用符で囲まれたキー内の引用符: 'quoted "value"' = "value"

  • 値内のエスケープされた引用符: str = "I'm a string. \"You can quote me\""

  • 浮動小数点と整数の混在: numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ]

  • 配列内の混合型: contributors = ["foo@example.com", { name = "Baz", email = "baz@example.com" }]

  • 引用符付きキーを含む括弧で囲まれたヘッダー: [foo."bar.baz"]

AMI を指定する

以下のいずれかの要件がある場合は、起動テンプレートの imageId フィールドで AMI ID を指定します。追加情報については、要件を選択してください。

ブートストラップとは、インスタンスの起動時に実行できるコマンドの追加を表す用語です。起動テンプレートを指定せずに、eksctl を使用して引数を bootstrap.sh スクリプトに渡すことができます。または、起動テンプレートのユーザーデータセクションに情報を指定することでこれを行うことができます。

eksctl without specifying a launch template

次の内容で、my-nodegroup.yaml という名前のファイルを作成します。example-value をすべて自分の値に置き換えてください。--apiserver-endpoint--b64-cluster-ca、および --dns-cluster-ip 引数はオプションです。しかし、これらを定義すると、bootstrap.sh スクリプトによる describeCluster 呼び出しを避けることができます。これは、プライベートクラスターのセットアップや、ノードを頻繁にスケールインおよびスケールアウトするクラスターで役立ちます。bootstrap.sh スクリプトの詳細については、「GitHub」で「bootstrap.sh」ファイルを参照してください。

  • 必須となる引数は、クラスター名 (my-cluster) のみです。

  • ami-1234567890abcdef0 で希望する値を取得するには、次のセクションの表を使用できます。

  • この例では、カスタムの max-pods 値を設定するために kubelet 引数を指定します。その際、Amazon EKS 最適化 AMI に含まれている bootstrap.sh スクリプトを使用します。my-max-pods-value の選択についての詳細は、「各 Amazon EC2 インスタンスタイプの Amazon EKS 推奨最大 pods 数」を参照してください。

  • クラスターの certificate-authority を取得するには、次のコマンドを実行します。

    aws eks describe-cluster --query "cluster.certificateAuthority.data" --output text --name my-cluster --region region-code
  • クラスターの api-server-endpoint を取得するには、次のコマンドを実行します。

    aws eks describe-cluster --query "cluster.endpoint" --output text --name my-cluster --region region-code
  • 最終的に、--dns-cluster-ip の値はサービス CIDR を示す .10 となります。クラスターの service-cidr を取得するには、次のコマンドを実行します。例えば、戻り値が ipv4 10.100.0.0/16 であれば、自分の値は 10.100.0.10 です。

    aws eks describe-cluster --query "cluster.kubernetesNetworkConfig.serviceIpv4Cidr" --output text --name my-cluster --region region-code
  • この例では、ノードグループの作成にランタイムとして containerd を使用しますが、必要に応じて変更できます。

--- apiVersion: eksctl.io/v1alpha5 kind: ClusterConfig metadata: name: my-cluster region: region-code managedNodeGroups: - name: my-nodegroup ami: ami-1234567890abcdef0 instanceType: m5.large privateNetworking: true disableIMDSv1: true labels: { x86-al2-specified-mng } overrideBootstrapCommand: | #!/bin/bash /etc/eks/bootstrap.sh my-cluster \ --kubelet-extra-args '--max-pods=my-max-pods-value' \ --b64-cluster-ca certificate-authority \ --apiserver-endpoint api-server-endpoint \ --dns-cluster-ip service-cidr.10 \ --use-max-pods false \ --container-runtime containerd

利用可能な eksctl config ファイルオプションについては、「eksctl ドキュメント」の「Config file schema」(Config ファイルスキーマ) を参照してください。eksctl ユーティリティは引き続き起動テンプレートを作成し、config ファイルに提供したデータを使用してユーザーデータを設定します。

次のコマンドを使用して、ノードグループを作成します。

eksctl create nodegroup --config-file=my-nodegroup.yaml
User data in a launch template

起動テンプレートのユーザーデータセクションで次の情報を指定します。example-value をすべて自分の値に置き換えてください。--apiserver-endpoint--b64-cluster-ca、および --dns-cluster-ip 引数はオプションです。しかし、これらを定義すると、bootstrap.sh スクリプトによる describeCluster 呼び出しを避けることができます。これは、プライベートクラスターのセットアップや、ノードを頻繁にスケールインおよびスケールアウトするクラスターで役立ちます。bootstrap.sh スクリプトの詳細については、「bootstrap.sh」で「GitHub」ファイルを参照してください。

  • 必須となる引数は、クラスター名 (my-cluster) のみです。

  • この例では、カスタムの max-pods 値を設定するために kubelet 引数を指定します。その際、Amazon EKS 最適化 AMI に含まれている bootstrap.sh スクリプトを使用します。my-max-pods-value の選択についての詳細は、「各 Amazon EC2 インスタンスタイプの Amazon EKS 推奨最大 pods 数」を参照してください。

  • クラスターの certificate-authority を取得するには、次のコマンドを実行します。

    aws eks describe-cluster --query "cluster.certificateAuthority.data" --output text --name my-cluster --region region-code
  • クラスターの api-server-endpoint を取得するには、次のコマンドを実行します。

    aws eks describe-cluster --query "cluster.endpoint" --output text --name my-cluster --region region-code
  • 最終的に、--dns-cluster-ip の値はサービス CIDR を示す .10 となります。クラスターの service-cidr を取得するには、次のコマンドを実行します。例えば、戻り値が ipv4 10.100.0.0/16 であれば、自分の値は 10.100.0.10 です。

    aws eks describe-cluster --query "cluster.kubernetesNetworkConfig.serviceIpv4Cidr" --output text --name my-cluster --region region-code
  • この例では、ノードグループの作成にランタイムとして containerd を使用しますが、必要に応じて変更できます。

MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="==MYBOUNDARY==" --==MYBOUNDARY== Content-Type: text/x-shellscript; charset="us-ascii" #!/bin/bash set -ex /etc/eks/bootstrap.sh my-cluster \ --kubelet-extra-args '--max-pods=my-max-pods-value' \ --b64-cluster-ca certificate-authority \ --apiserver-endpoint api-server-endpoint \ --dns-cluster-ip service-cidr.10 \ --use-max-pods false \ --container-runtime containerd --==MYBOUNDARY==--

詳細については、Linux インスタンス用 Amazon EC2 ユーザーガイドAmazon マシンイメージ (AMI) を参照してください。Amazon EKS AMI ビルド仕様には、Amazon Linux 2 をベースにしたカスタム Amazon EKS AMI を構築するための、リソースと設定スクリプトが含まれています。詳細については、「GitHub」の「Amazon EKS AMI ビルド仕様」を参照してください。他のオペレーティングシステムがインストールされたカスタム AMI を作成するには、「GitHub」の「Amazon EKS Sample Custom AMIs」を参照してください。

重要

AMI を指定する際、Amazon EKS ではユーザーデータをマージしません。代わりに、ノードのクラスターへの参加に必要な bootstrap コマンドを、ユーザーが提供する必要があります。ノードがクラスターに参加できない場合、Amazon EKS CreateNodegroup および UpdateNodegroupVersion アクションも失敗します。

以下に、マネージド型ノードグループで AMI ID を指定する際の制限と条件を示します。

  • 起動テンプレートで AMI ID を指定する場合と、AMI ID を指定しない場合は、新しいノードグループを作成して切り替える必要があります。

  • 新しい AMI バージョンが利用可能になっても、コンソールでは通知を表示しません。ノードグループを新しい AMI バージョンに更新するには、更新された AMI ID で新しいバージョンの起動テンプレートを作成する必要があります。次に、新しい起動テンプレートバージョンでノードグループを更新する必要があります。

  • AMI ID を指定した場合は、API の次のフィールドを設定することはできません。

    • amiType

    • releaseVersion

    • version

  • マネージド型ノードグループでは Windows を使用できないため、Windows の AMI ID を指定することはできません。