From 7947229564f147367246a845aa9da8c045a9f24f Mon Sep 17 00:00:00 2001 From: Aleksei Sizov Date: Mon, 7 Oct 2024 15:50:51 -0500 Subject: [PATCH] Update docs according to the new credential system --- docs/aws/cluster-parameters.md | 60 ++++++++++++++++++++++++++++-- docs/aws/credentials.md | 35 ----------------- docs/aws/main.md | 4 -- docs/azure/cluster-parameters.md | 6 +-- docs/credential/main.md | 49 ++++++++++++++++++++++++ docs/vsphere/cluster-parameters.md | 15 +++----- 6 files changed, 114 insertions(+), 55 deletions(-) delete mode 100644 docs/aws/credentials.md create mode 100644 docs/credential/main.md diff --git a/docs/aws/cluster-parameters.md b/docs/aws/cluster-parameters.md index 35bde3e..c30a696 100644 --- a/docs/aws/cluster-parameters.md +++ b/docs/aws/cluster-parameters.md @@ -3,8 +3,61 @@ ## Software prerequisites 1. `clusterawsadm` CLI installed locally. -2. `AWS_B64ENCODED_CREDENTIALS` environment variable to be exported. -See [AWS credentials](credentials.md#aws-credentials-configuration) (p. 1-3) + +## Cluster Identity + +To provide credentials for CAPI AWS provider (CAPA) `ClusterIdentity` object +must be created. + +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). + +To create `ClusterIdentity` IAM user must be created and assigned with the +following roles: + +- `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` + +Follow the [IAM setup guide](cloudformation.md#aws-iam-setup) (if not already) +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 create +like so: + +```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). ## AWS AMI @@ -13,7 +66,7 @@ will be used). You can override lookup parameters to search your desired image automatically or use AMI ID directly. -If both AMI ID and lookup paramters are defined AMI ID will have higher precedence. +If both AMI ID and lookup parameters are defined AMI ID will have higher precedence. ### Image lookup @@ -72,6 +125,7 @@ metadata: name: cluster-1 spec: template: aws-standalone-cp + credential: aws-cred config: sshKeyName: foobar bastion: diff --git a/docs/aws/credentials.md b/docs/aws/credentials.md deleted file mode 100644 index 08de1df..0000000 --- a/docs/aws/credentials.md +++ /dev/null @@ -1,35 +0,0 @@ -# AWS Credentials configuration - -1. Ensure AWS user has enough permissions to deploy cluster. Ensure that these policies were attached to the AWS user: - -* `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. Retrieve access key and export it as environment variable: - -``` -export AWS_REGION= -export AWS_ACCESS_KEY_ID= -export AWS_SECRET_ACCESS_KEY= -export AWS_SESSION_TOKEN= # Optional. If you are using Multi-Factor Auth. -``` - -3. Create the base64 encoded credentials using `clusterawsadm`: - -``` -export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm bootstrap credentials encode-as-profile) -``` - -4. Create the secret with AWS variables: - -> By default, HMC fetches the AWS variables configuration from the `aws-variables` secret in the `hmc-system` -> namespace. If you want to change the name of the secret you should overwrite the configuration of the cluster -> API provider AWS in the HMC Management object. \ -> For details, see: [Extended Management Configuration](../install/installation.md#extended-management-configuration) - -> You can also provide additional configuration variables, but the `AWS_B64ENCODED_CREDENTIALS` parameter is required. - -``` -kubectl create secret generic aws-variables -n hmc-system --from-literal AWS_B64ENCODED_CREDENTIALS="$AWS_B64ENCODED_CREDENTIALS" -``` diff --git a/docs/aws/main.md b/docs/aws/main.md index 275919c..060d35f 100644 --- a/docs/aws/main.md +++ b/docs/aws/main.md @@ -9,10 +9,6 @@ Follow the AWS IAM [setup quide](cloudformation.md#aws-iam-setup). -## Configure AWS credentials - -Follow the AWS Credentials [configuration quide](credentials.md#aws-credentials-configuration). - ## AWS cluster parameters Follow the [AWS Cluster Parameters guide](cluster-parameters.md#aws-cluster-parameters) diff --git a/docs/azure/cluster-parameters.md b/docs/azure/cluster-parameters.md index 410b1fa..4ad16ea 100644 --- a/docs/azure/cluster-parameters.md +++ b/docs/azure/cluster-parameters.md @@ -74,9 +74,9 @@ spec: type: ServicePrincipal ``` -These objects then should be referenced in the `ManagedCluster` object in the -`.spec.config.clusterIdentity` field. - Subscription ID which was used to create service principal should be the same that will be used in the `.spec.config.subscriptionID` field of the `ManagedCluster` object. + +To use `AzureClusterIdentity` it should be referenced in the `Credential` +object. For more details check the [credential section](../credential/main.md). diff --git a/docs/credential/main.md b/docs/credential/main.md new file mode 100644 index 0000000..cc4d9ec --- /dev/null +++ b/docs/credential/main.md @@ -0,0 +1,49 @@ +# Credential system + +In order for infrastructure provider to work properly a correct credentials +should be passed to it. The following describes how it is implemented in 2A. + +## The process + +The following is the process of passing credentials to the system: + +1. Provider specific `ClusterIdentity` and `Secret` is created +2. `Credential` object is created referencing `ClusterIdentity` from step 1. +3. The `Credential` object is then referenced in the `ManagedCluster`. + +By design steps 1 and 2 should be executed by the platform lead engender who has +access to the credentials. Thus credentials could be used by platform engineers +without a need to have access to actual credentials or underlying resources, +like `ClusterIndentity`. + +## Credential object + +The `Credential` object acts like a reference to the underlying credentials. It is +namespace-scoped, which means that it must be in the same `Namespace` with the +`ManagedCluster` it is referenced in. +Actual credentials can be located in any namespace. + +### Example + +```yaml +--- +apiVersion: hmc.mirantis.com/v1alpha1 +kind: Credential +metadata: + name: azure-credential + namespace: dev +spec: + description: "Main Azure credentials" + identityRef: + apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 + kind: AzureClusterIdentity + name: azure-cluster-identity + namespace: hmc-system +``` + +In the example above `Credential` object is referencing `AzureClusterIdentity` +which was created in the `hmc-system` namespace. + +The `.spec.description` field can be used to provide arbitrary description of the +object, so user could make a decision which credentials to use if several are +present. diff --git a/docs/vsphere/cluster-parameters.md b/docs/vsphere/cluster-parameters.md index c52f44d..1d95c1f 100644 --- a/docs/vsphere/cluster-parameters.md +++ b/docs/vsphere/cluster-parameters.md @@ -35,7 +35,6 @@ apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 kind: VSphereClusterIdentity metadata: name: vsphere-cluster-identity - namespace: hmc-system spec: secretName: vsphere-cluster-identity-secret allowedNamespaces: @@ -43,9 +42,11 @@ spec: matchLabels: {} ``` -These objects then should be referenced in the `ManagedCluster` object in the -`.spec.config.clusterIdentity` field. +To be used for the cluster creation.`VsphereClusterIdentity` then should be +referenced in the `Credential` object. +For more details regarding the credential system check the [credential section](../credential/main.md) +of the docs. ## ManagedCluster parameters @@ -65,8 +66,6 @@ for successful cluster creation. | `.spec.config.vsphere.datastore` | `/DC/datastore/DS` | Datastore path | | `.spec.config.vsphere.resourcePool` | `/DC/host/vCluster/Resources/ResPool` | Resource pool path | | `.spec.config.vsphere.folder` | `/DC/vm/example` | vSphere folder path | -| `.spec.config.vsphere.username` | `user` | Username for your vSphere instance | -| `.spec.config.vsphere.password` | `password` | Password for your vSphere instance | _You can check [machine parameters](machine-parameters.md) for machine specific parameters._ @@ -77,9 +76,6 @@ To obtain vSphere certificate thumbprint you can use the following command: curl -sw %{certs} https://vcenter.example.com | openssl x509 -sha256 -fingerprint -noout | awk -F '=' '{print $2}' ``` -Username and password currently must be passed once more in the `ManagedCluster` -object to provide proper authentication for CCM and CSI driver. - ## Example of ManagedCluster CR With all above parameters provided your `ManagedCluster` can look like this: @@ -91,6 +87,7 @@ metadata: name: cluster-1 spec: template: vsphere-standalone-cp + credential: vsphere-credential config: clusterIdentity: name: vsphere-cluster-identity @@ -101,8 +98,6 @@ spec: datastore: "/DC/datastore/DC" resourcePool: "/DC/host/vCluster/Resources/ResPool" folder: "/DC/vm/example" - username: "user" - password: "Passw0rd" controlPlaneEndpointIP: "172.16.0.10" controlPlane: