sigs.k8s.io/cluster-api-provider-aws@v1.5.5/docs/book/src/topics/using-clusterawsadm-to-fulfill-prerequisites.md (about)

     1  <!-- NB: This page is meant to be embedded in Cluster API book -->
     2  # Using clusterawsadm to fulfill prerequisites
     3  
     4  ## Requirements
     5  
     6  - Linux or MacOS (Windows isn't supported at the moment).
     7  - AWS credentials.
     8  - [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)
     9  - [jq](https://stedolan.github.io/jq/download/)
    10  
    11  ## IAM resources
    12  
    13  ### With `clusterawsadm`
    14  
    15  Get the latest [clusterawsadm](https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases)
    16  and place it in your path.
    17  
    18  Cluster API Provider AWS ships with clusterawsadm, a utility to help you manage
    19  IAM objects for this project.
    20  
    21  In order to use clusterawsadm you must have an administrative user in an AWS account.
    22  Once you have that administrator user you need to set your environment variables:
    23  
    24  * `AWS_REGION`
    25  * `AWS_ACCESS_KEY_ID`
    26  * `AWS_SECRET_ACCESS_KEY`
    27  * `AWS_SESSION_TOKEN` (if you are using Multi-factor authentication)
    28  
    29  After these are set run this command to get you up and running:
    30  
    31  ```bash
    32  clusterawsadm bootstrap iam create-cloudformation-stack
    33  ```
    34  
    35  Additional policies can be added by creating a configuration file
    36  
    37  ```yaml
    38  apiVersion: bootstrap.aws.infrastructure.cluster.x-k8s.io/v1beta1
    39  kind: AWSIAMConfiguration
    40  spec:
    41    controlPlane:
    42      extraPolicyAttachments:
    43        - arn:aws:iam::<AWS_ACCOUNT>:policy/my-policy
    44        - arn:aws:iam::aws:policy/AmazonEC2FullAccess
    45    nodes:
    46      extraPolicyAttachments:
    47        - arn:aws:iam::<AWS_ACCOUNT>:policy/my-other-policy
    48  ```
    49  
    50  and passing it to clusterawsadm as follows
    51  
    52  ```bash
    53  clusterawsadm bootstrap iam create-cloudformation-stack --config bootstrap-config.yaml
    54  ```
    55  
    56  These will be added to the control plane and node roles respectively when they are created.
    57  
    58  > **Note:** If you used the now deprecated `clusterawsadm alpha bootstrap` 0.5.4 or earlier to create IAM objects for the
    59  > Cluster API Provider for AWS, using `clusterawsadm bootstrap iam` 0.5.5 or later will, by default, remove the bootstrap
    60  > user and group. Anything using those credentials to authenticate will start experiencing authentication failures. If you
    61  > rely on the bootstrap user and group credentials, specify `bootstrapUser.enable = true` in the configuration file, like
    62  > this:
    63  >
    64  > ```yaml
    65  > apiVersion: bootstrap.aws.infrastructure.cluster.x-k8s.io/v1beta1
    66  > kind: AWSIAMConfiguration
    67  > spec:
    68  >   bootstrapUser:
    69  >     enable: true
    70  > ```
    71  
    72  #### With EKS Support
    73  
    74  The pre-requisities for EKS are enabled by default. However, if you want to use some of the optional features of EKS (see [here](eks/enabling.md) for more information on what these are) then you will need to enable these features via the configuration file. For example:
    75  
    76  ```yaml
    77  apiVersion: bootstrap.aws.infrastructure.cluster.x-k8s.io/v1beta1
    78  kind: AWSIAMConfiguration
    79  spec:
    80    eks:
    81      iamRoleCreation: false # Set to true if you plan to use the EKSEnableIAM feature flag to enable automatic creation of IAM roles
    82      managedMachinePool:
    83        disable: false # Set to false to enable creation of the default node role for managed machine pools
    84      fargate:
    85        disable: false # Set to false to enable creation of the default role for the fargate profiles
    86  ```
    87  
    88  and then use that configuration file:
    89  
    90  ```bash
    91  clusterawsadm bootstrap iam create-cloudformation-stack --config bootstrap-config.yaml
    92  ```
    93  
    94  #### Enabling EventBridge Events
    95  
    96  To enable EventBridge instance state events, additional permissions must be granted along with enabling the feature-flag.
    97  Additional permissions for events and queue management can be enabled through the configuration file as follows:
    98  
    99  ```yaml
   100  apiVersion: bootstrap.aws.infrastructure.cluster.x-k8s.io/v1beta1
   101  kind: AWSIAMConfiguration
   102  spec:
   103    ...
   104    eventBridge:
   105      enable: true
   106    ...
   107  ```
   108  
   109  
   110  
   111  ### Without `clusterawsadm`
   112  
   113  This is not a recommended route as the policies are very specific and will
   114  change with new features.
   115  
   116  If you do not wish to use the `clusteradwsadm` tool then you will need to
   117  understand exactly which IAM policies and groups we are expecting. There are
   118  several policies, roles and users that need to be created. Please see our
   119  [controller policy][controllerpolicy] file to understand the permissions that are necessary.
   120  
   121  You can use `clusteradwadm` to print out the needed IAM policies, e.g.
   122  
   123  ```bash
   124  clusterawsadm bootstrap iam print-policy --document AWSIAMManagedPolicyControllers --config bootstrap-config.yaml
   125  ```
   126  
   127  [controllerpolicy]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/0e543e0eb30a7065c967f5df8d6abd872aa4ff0c/pkg/cloud/aws/services/cloudformation/bootstrap.go#L149-L188
   128  
   129  ## SSH Key pair
   130  
   131  If you plan to use SSH to access the instances created by Cluster API Provider AWS
   132  then you will need to specify the name of an existing SSH key pair within the region
   133  you plan on using. If you don't have one yet, a new one needs to be created.
   134  
   135  ### Create a new key pair
   136  
   137  ```bash
   138  # Save the output to a secure location
   139  aws ec2 create-key-pair --key-name default --output json | jq .KeyMaterial -r
   140  -----BEGIN RSA PRIVATE KEY-----
   141  [... contents omitted ...]
   142  -----END RSA PRIVATE KEY-----
   143  ```
   144  
   145  If you want to save the private key directly into AWS Systems Manager Parameter
   146  Store with KMS encryption for security, you can use the following command:
   147  
   148  ```bash
   149  aws ssm put-parameter --name "/sigs.k8s.io/cluster-api-provider-aws/ssh-key" \
   150    --type SecureString \
   151    --value "$(aws ec2 create-key-pair --key-name default --output json | jq .KeyMaterial -r)"
   152  ```
   153  
   154  ### Adding an existing public key to AWS
   155  
   156  ```bash
   157  # Replace with your own public key
   158  aws ec2 import-key-pair \
   159    --key-name default \
   160    --public-key-material "$(cat ~/.ssh/id_rsa.pub)"
   161  ```
   162  
   163  > **NB**: Only RSA keys are supported by AWS.
   164  
   165  ## Setting up the environment
   166  
   167  The current iteration of the Cluster API Provider AWS relies on credentials
   168  being present in your environment. These then get written into the cluster
   169  manifests for use by the controllers.
   170  
   171  E.g.
   172  
   173  ```bash
   174  export AWS_REGION=us-east-1 # This is used to help encode your environment variables
   175  export AWS_ACCESS_KEY_ID=<your-access-key>
   176  export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
   177  export AWS_SESSION_TOKEN=<session-token> # If you are using Multi-Factor Auth.
   178  ```
   179  
   180  **Note**: The credentials used must have the appropriate permissions for use by the controllers.
   181  You can get the required policy statement by using the following command:
   182  
   183  ```bash
   184  clusterawsadm bootstrap iam print-policy --document AWSIAMManagedPolicyControllers --config bootstrap-config.yaml
   185  ```
   186  
   187  > To save credentials securely in your environment, [aws-vault](https://github.com/99designs/aws-vault) uses
   188  > the OS keystore as permanent storage, and offers shell features to securely
   189  > expose and setup local AWS environments.