From d8d2b924ce611a8faa4058169b9d6bc1be077556 Mon Sep 17 00:00:00 2001 From: Shaun O'Meara Date: Thu, 17 Oct 2024 21:54:56 -0400 Subject: [PATCH] AWS docs cleanup and alignment to new creds --- docs/aws/cloudformation.md | 3 +- docs/aws/cluster-parameters.md | 128 +++++++++++++++++++++---------- docs/aws/hosted-control-plane.md | 4 +- docs/aws/main.md | 30 ++++++-- 4 files changed, 116 insertions(+), 49 deletions(-) diff --git a/docs/aws/cloudformation.md b/docs/aws/cloudformation.md index 37736ea..ed34e38 100644 --- a/docs/aws/cloudformation.md +++ b/docs/aws/cloudformation.md @@ -1,6 +1,7 @@ # AWS IAM setup -Before launching a cluster on AWS, it's crucial to set up your AWS infrastructure provider: +Before launching a cluster on AWS, you need to set up your AWS infrastructure with the +necessary IAM policies and service account(see cluster parameters for more). > NOTE: > Skip steps below if you've already configured IAM policy for your account diff --git a/docs/aws/cluster-parameters.md b/docs/aws/cluster-parameters.md index f3eff02..5240b41 100644 --- a/docs/aws/cluster-parameters.md +++ b/docs/aws/cluster-parameters.md @@ -3,8 +3,12 @@ ## Software prerequisites 1. `clusterawsadm` CLI installed locally. +2. `kubectl` CLI installed locally -## Cluster Identity +## Cluster Identity + +> NOTE: +> Full details on the Credentials system can be found in the [Credential System Guide](/credential/main/) To provide credentials for CAPI AWS provider (CAPA) `ClusterIdentity` object must be created. @@ -13,50 +17,94 @@ AWS provider supports 3 types of `ClusterIdentity`, which one to use depends on your specific use case. More information regarding CAPA `ClusterIdentity` resources could be found in [CRD Reference](https://cluster-api-aws.sigs.k8s.io/crd/). -In this example we're using [`AWSClusterStaticIdentity`](https://cluster-api-aws.sigs.k8s.io/crd/#infrastructure.cluster.x-k8s.io/v1beta1.AWSClusterStaticIdentity). +## AWS Cluster Static Identity Example -To create `ClusterIdentity` IAM user must be created and assigned with the -following roles: +### Create AWS IAM User +> In this example we're using [`AWSClusterStaticIdentity`](https://cluster-api-aws.sigs.k8s.io/crd/#infrastructure.cluster.x-k8s.io/v1beta1.AWSClusterStaticIdentity). -- `control-plane.cluster-api-provider-aws.sigs.k8s.io` -- `controllers.cluster-api-provider-aws.sigs.k8s.io` -- `nodes.cluster-api-provider-aws.sigs.k8s.io` +1. Create a AWS IAM user to use as service account -Follow the [IAM setup guide](cloudformation.md#aws-iam-setup) (if not already) + A IAM user must be created and assigned the following roles: + > Follow the [IAM setup guide](cloudformation.md#aws-iam-setup) (if not already done) to create these roles. -Next the following secret should be created with the user's credentials: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: aws-cred-secret - namespace: hmc-system -type: Opaque -stringData: - AccessKeyID: "AAAEXAMPLE" - SecretAccessKey: "++AQDEXAMPLE" -``` - -> NOTE: -> The secret must be created in the same `Namespace` where CAPA provider is -> running. In case of Project 2A it's currently `hmc-system`. Placing secret in -> any other `Namespace` will result controller not able to read it. - -After the `Secret` was created the `AWSClusterStaticIdentity` must be created: - -```yaml -apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 -kind: AWSClusterStaticIdentity -metadata: - name: aws-cluster-identity -spec: - secretRef: aws-cred-secret -``` - -To use these newly created credentials the `Credential` object must be -created. It is described in detail in the [credential section](../credential/main.md). + - `control-plane.cluster-api-provider-aws.sigs.k8s.io` + - `controllers.cluster-api-provider-aws.sigs.k8s.io` + - `nodes.cluster-api-provider-aws.sigs.k8s.io` + + +2. Create Access Keys for the IAM user + + In the AWS IAM Console create the Access Keys for the IAM user and download them. + + You should have a `AccessKeyID` and a `SecretAccessKey` that looks like the following + ``` + Access key ID,Secret access key + AKIAQF+EXAMPLE, EdJfFar6+example + ``` + +### Create the IAM Credentials on Kubernetes + +1. Next the following secret should be created with the user's credentials + + > The `name:` entry must be unique + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: aws-cluster-identity-secret + namespace: hmc-system + type: Opaque + stringData: + AccessKeyID: AKIAQF+EXAMPLE + SecretAccessKey: EdJfFar6+example + ``` + + > NOTE: + > The secret must be created in the same `Namespace` where CAPA provider is + > running. In case of Project 2A it's currently `hmc-system`. Placing secret in + > any other `Namespace` will result controller not able to read it. + +2. Then `AWSClusterStaticIdentity` must be created + + > The `secretRef` must match the `name` of the secret that was created in the previous step + + ```yaml + apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 + kind: AWSClusterStaticIdentity + metadata: + name: aws-cluster-identity + namespace: hmc-system + spec: + secretRef: aws-cluster-identity-secret + allowedNamespaces: + selector: + matchLabels: {} + ``` + +3. Finally the `Credential` object needs to be created + + In the `identityRef:` section the `kind:` must be `AWSClusterStaticIdentity` and the `name:` must match of the `AWSClusterStaticIdentity` object. + + ```yaml + apiVersion: hmc.mirantis.com/v1alpha1 + kind: Credential + metadata: + name: aws-cluster-identity-cred + namespace: hmc-system + spec: + description: "Credential Example" + identityRef: + apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 + kind: AWSClusterStaticIdentity + name: aws-cluster-identity + namespace: hmc-system + ``` + + > NOTE: + > To use these newly created credentials the `Credential` object must be + > created. It is described in detail in the [credential section](../credential/main.md). ## AWS AMI diff --git a/docs/aws/hosted-control-plane.md b/docs/aws/hosted-control-plane.md index 32ccea3..3ca5494 100644 --- a/docs/aws/hosted-control-plane.md +++ b/docs/aws/hosted-control-plane.md @@ -1,4 +1,6 @@ -# Hosted control plane (k0smotron) deployment +# AWS Hosted control plane deployment + +This section covers setting up for a K0smotron hosted control plane on AWS. ## Prerequisites diff --git a/docs/aws/main.md b/docs/aws/main.md index 2a4c988..9f83f8b 100644 --- a/docs/aws/main.md +++ b/docs/aws/main.md @@ -1,14 +1,30 @@ -# Prepare the AWS infrastructure provider +# AWS infrastructure provider -## Software prerequisites +The AWS Infrastructure provider within 2A provides for several deployment +options these include: -1. `kubectl` CLI installed locally. -2. `clusterawsadm` CLI installed locally. +Current: -## Configure AWS IAM +- Colocated Control Plane and Worker +- Hosted Control Plane -Follow the AWS IAM [setup guide](cloudformation.md#aws-iam-setup). +Planned or in Progress: + +- EKS Deployments + +Prior to being able to deploy a cluster to AWS you need to setup the +AWS IAM policies and prepare the cluster credentials. + +## Prerequisites + +1. Adminstrative user in AWS with right to create IAM users and policies +2. `kubectl` CLI installed locally +3. `clusterawsadm` CLI installed locally + +## Configure AWS IAM + +Start here and follow the AWS IAM [setup guide](cloudformation.md#aws-iam-setup). ## AWS cluster parameters -Follow the [AWS Cluster Parameters guide](cluster-parameters.md#aws-cluster-parameters). +To configure more cluster parameters follow the [AWS Cluster Parameters guide](cluster-parameters.md#aws-cluster-parameters).