sigs.k8s.io/cluster-api-provider-aws@v1.5.5/docs/book/src/topics/machinepools.md (about)

     1  # MachinePools
     2  
     3  - **Feature status:** Experimental
     4  - **Feature gate:** MachinePool=true
     5  
     6  MachinePool allows users to manage many machines as a single entity. Infrastructure providers implement a separate CRD that handles infrastructure side of the feature.
     7  
     8  ## AWSMachinePool
     9  
    10  Cluster API Provider AWS (CAPA) has experimental support for `MachinePool` though the infrastructure type `AWSMachinePool`. An `AWSMachinePool` corresponds to an [AWS AutoScaling Groups](https://docs.aws.amazon.com/autoscaling/ec2/userguide/AutoScalingGroup.html), which provides the cloud provider specific resource for orchestrating a group of EC2 machines.
    11  
    12  The AWSMachinePool controller creates and manages an AWS AutoScaling Group using launch templates so users don't have to manage individual machines. You can use Autoscaling health checks for replacing instances and it will maintain the number of instances specified.
    13  
    14  ### Using `clusterctl` to deploy
    15  
    16  To deploy a MachinePool / AWSMachinePool via `clusterctl generate` there's a [flavor](https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster.html#flavors) for that.
    17  
    18  Make sure to set up your AWS environment as described [here](https://cluster-api.sigs.k8s.io/user/quick-start.html).
    19  
    20  ```shell
    21  export EXP_MACHINE_POOL=true
    22  clusterctl init --infrastructure aws
    23  clusterctl generate cluster my-cluster --kubernetes-version v1.16.8 --flavor machinepool > my-cluster.yaml
    24  ```
    25  
    26  The template used for this [flavor](https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster.html#flavors) is located [here](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/main/templates/cluster-template-machinepool.yaml).
    27  
    28  ## AWSManagedMachinePool
    29  
    30  Cluster API Provider AWS (CAPA) has experimental support for [EKS Managed Node Groups](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html) using `MachinePool` through the infrastructure type `AWSManagedMachinePool`. An `AWSManagedMachinePool` corresponds to an [AWS AutoScaling Groups](https://docs.aws.amazon.com/autoscaling/ec2/userguide/AutoScalingGroup.html) that is used for an EKS managed node group. .
    31  
    32  The AWSManagedMachinePool controller creates and manages an EKS managed node group with in turn manages an AWS AutoScaling Group of managed EC2 instance types.
    33  
    34  To use the managed machine pools certain IAM permissions are needed. The easiest way to ensure the required IAM permissions are in place is to use `clusterawsadm` to create them. To do this, follow the EKS instructions in [using clusterawsadm to fulfill prerequisites](using-clusterawsadm-to-fulfill-prerequisites.md).
    35  
    36  ### Using `clusterctl` to deploy
    37  
    38  To deploy an EKS managed node group using AWSManagedMachinePool via `clusterctl generate` you can use a [flavor](https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster.html#flavors).
    39  
    40  Make sure to set up your AWS environment as described [here](https://cluster-api.sigs.k8s.io/user/quick-start.html).
    41  
    42  ```shell
    43  export EXP_MACHINE_POOL=true
    44  clusterctl init --infrastructure aws
    45  clusterctl generate cluster my-cluster --kubernetes-version v1.16.8 --flavor eks-managedmachinepool > my-cluster.yaml
    46  ```
    47  
    48  The template used for this [flavor](https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster.html#flavors) is located [here](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/main/templates/cluster-template-eks-managedmachinepool.yaml).
    49  
    50  
    51  ## Examples
    52  
    53  ### Example: MachinePool, AWSMachinePool and KubeadmConfig Resources
    54  
    55  Below is an example of the resources needed to create a pool of EC2 machines orchestrated with
    56  an AWS Auto Scaling Group.
    57  
    58  ```yaml
    59  ---
    60  apiVersion: cluster.x-k8s.io/v1beta1
    61  kind: MachinePool
    62  metadata:
    63    name: capa-mp-0
    64  spec:
    65    clusterName: capa
    66    replicas: 2
    67    template:
    68      spec:
    69        bootstrap:
    70          configRef:
    71            apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
    72            kind: KubeadmConfig
    73            name: capa-mp-0
    74        clusterName: capa
    75        infrastructureRef:
    76          apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    77          kind: AWSMachinePool
    78          name: capa-mp-0
    79        version: v1.16.8
    80  ---
    81  apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    82  kind: AWSMachinePool
    83  metadata:
    84    name: capa-mp-0
    85  spec:
    86    minSize: 1
    87    maxSize: 10
    88    availabilityZones:
    89      - "${AWS_AVAILABILITY_ZONE}"
    90    awsLaunchTemplate:
    91      instanceType: "${AWS_CONTROL_PLANE_MACHINE_TYPE}"
    92      sshKeyName: "${AWS_SSH_KEY_NAME}"
    93    subnets:
    94      - id : "${AWS_SUBNET_ID}"
    95  ---
    96  apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
    97  kind: KubeadmConfig
    98  metadata:
    99    name: capa-mp-0
   100    namespace: default
   101  spec:
   102    joinConfiguration:
   103      nodeRegistration:
   104        name: '{{ ds.meta_data.local_hostname }}'
   105        kubeletExtraArgs:
   106          cloud-provider: aws
   107  ```
   108  
   109  ## Autoscaling
   110  
   111  [`cluster-autoscaler`](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler) can be used to scale MachinePools up and down.
   112  Two providers are possible to use with CAPA MachinePools: `clusterapi`, or `aws`.
   113  
   114  If the `AWS` autoscaler provider is used, each MachinePool needs to have an annotation set to prevent scale up/down races between
   115  cluster-autoscaler and cluster-api. Example:
   116  
   117  ```yaml
   118  apiVersion: cluster.x-k8s.io/v1beta1
   119  kind: MachinePool
   120  metadata:
   121    name: capa-mp-0
   122    annotations:
   123      cluster.x-k8s.io/replicas-managed-by: "external-autoscaler"
   124  spec:
   125    clusterName: capa
   126    replicas: 2
   127    template:
   128      spec:
   129        bootstrap:
   130          configRef:
   131            apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
   132            kind: KubeadmConfig
   133            name: capa-mp-0
   134        clusterName: capa
   135        infrastructureRef:
   136          apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
   137          kind: AWSMachinePool
   138          name: capa-mp-0
   139        version: v1.24.0
   140  ```
   141  
   142  When using GitOps, make sure to ignore differences in `spec.replicas` on MachinePools. Example when using ArgoCD:
   143  
   144  ```yaml
   145    ignoreDifferences:
   146      - group: cluster.x-k8s.io
   147        kind: MachinePool
   148        jsonPointers:
   149          - /spec/replicas
   150  ```