Skip to content

Deploy an MKE 4 AWS child cluster#

The instructions herein assume that you are familiar with the k0rdent platform and the basics of how to deploy child clusters.

Info

Before you deploy child clusters, you must first enable the k0smotron and AWS Cluster API (CAPI) cloud providers. This is a one-time-only operation, which you do by issuing the following command:

kubectl patch management kcm --type='json' -p='[{"op":"add","path":"/spec/providers/-","value":{"name":"cluster-api-provider-aws"}},{"op":"add","path":"/spec/providers/-","value":{"name":"cluster-api-provider-k0sproject-k0smotron"}}]'

The sequence of the tutorial is as follows:

  1. Ensure that the prerequsities are met.
  2. Create the credentials objects and the resource template ConfigMap.
  3. Set the child cluster configuration.
  4. Verify child cluster readiness.
  5. Connect to the cluster with the kubeconfig.
  6. Connect directly to the child cluster.

Prerequisites#

  • An MKE 4 management cluster, with an associated kubectl-authenticated user.

  • A MKE 4 user serving as the AWS IAM user in the AWS account within which the child cluster is to be deployed, with the following CAPA-published IAM policies attached:

    • 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
    • controllers-eks.cluster-api-provider-aws.sigs.k8s.io

    For more information, refer to the official CAPA IAM permissions documentation.

  • A target AWS region with the requisite free Elastic IP / public IP capacity. By default, CAPA consumes one public IP per Availability Zone in use by the cluster. If you hit the regional EIP quota, request an increase before you run the tutorial.

Create the credentials objects#

Certain credentials objects are reqired to access AWS resources, including:

  • Secret
  • AWSClusterStaticIdentity
  • Credential
  • ConfigMap

Create the AWS credentials Secret object#

The AWS credentials Secret stores the access key ID and secret access key for your AWS account. You create an IAM Secret on the management cluster that contains credentials for the MKE 4 user and apply this to the management cluster that is running Mirantis k0rdent Enterprise, in the k0rdent namespace.

  1. Create the following aws-cluster-identity-secret.yaml file:

    apiVersion: v1
kind: Secret
metadata:
  name: aws-cluster-identity-secret
  namespace: k0rdent
  labels:
    k0rdent.mirantis.com/component: "kcm"
type: Opaque
stringData:
  AccessKeyID: "EXAMPLE_ACCESS_KEY_ID"
  SecretAccessKey: "EXAMPLE_SECRET_ACCESS_KEY"

    Important

    The Access Key ID and Secret Access Key are the same ones you generated for the MKE 4 AWS AIM user.

  2. Apply the aws-cluster-identity-secret.yaml file to the management cluster:

    kubectl apply -f aws-cluster-identity-secret.yaml

Create the AWSClusterStaticIdentity object#

The AWSClusterStaticIdentity object defines the CAPA identity that uses the Secret.

  1. Create the following aws-cluster-identity.yaml file:

    apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
kind: AWSClusterStaticIdentity
metadata:
  name: aws-cluster-identity
  labels:
    k0rdent.mirantis.com/component: "kcm"
spec:
  secretRef: aws-cluster-identity-secret
  allowedNamespaces: {}

    Note

    The spec.secretRef is the same as the metadata.name of the Secret.

  2. Apply the aws-cluster-identity.yaml file to create the object:

    kubectl apply -f aws-cluster-identity.yaml

Create the Credential object#

  1. Create the following aws-cluster-identity-cred.yaml file:

    apiVersion: k0rdent.mirantis.com/v1beta1
kind: Credential
metadata:
  name: aws-cluster-identity-cred
  namespace: k0rdent
spec:
  description: "Credential Example"
  identityRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
    kind: AWSClusterStaticIdentity
    name: aws-cluster-identity

    Important

    .spec.identityRef.kind must be AWSClusterStaticIdentity and .spec.identityRef.name must match the .metadata.name of the AWSClusterStaticIdentity object.

  2. Apply the aws-cluster-identity-cred.yaml file to the management cluster:

    kubectl apply -f aws-cluster-identity-cred.yaml

Create the Mirantis k0rdent Enterprise Cluster Identity resource template ConfigMap#

  1. Create the following aws-cluster-identity-resource-template.yaml file:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-cluster-identity-resource-template
  namespace: k0rdent
  labels:
    k0rdent.mirantis.com/component: "kcm"
  annotations:
    projectsveltos.io/template: "true"

    Note

    ConfigMap is empty. This is expected, as it is not necessary to template any object inside a child cluster, however the object is available for future use, should the need arise.

  2. Apply the aws-cluster-identity-resource-template.yaml file to the management cluster:

    kubectl apply -f aws-cluster-identity-resource-template.yaml

Set the child cluster configuration#

Prepare and apply the child cluster configuration yaml file.

  1. Create the following mke-child-cluster.yaml file:

    Note

    spec.version must be set to the same MKE 4 version on which you are running the management cluster.

    apiVersion: mke.mirantis.com/v1alpha1
kind: MkeChildConfig
metadata:
  name: my-mke-child
  namespace: k0rdent
spec:
  version: v4.2.0
  registries:
    chartRegistry:
      url: oci://registry.mirantis.com/mke
    imageRegistry:
      url: registry.mirantis.com/mke
  infrastructure:
    provider: aws
    credential: aws-cluster-identity-cred
    region: eu-west-3

    Refer to Infrastructure options for descriptions of every supported field in spec.infrastructure and the provider-specific spec.infrastructure.configuration block.

  2. Apply the mke-child-cluster.yaml file:

    kubectl apply -f mke-child-cluster.yaml

Verify child cluster readiness#

Check the created object and ensure that the child cluster is ready:

kubectl -n k0rdent get mkechildconfig

Example output:

kubectl -n k0rdent get mkechildconfig
NAME                    READY   VERSION         LICENSE      STATUS            AGE
my-mke-child            True    v4.2.0          unlicensed   Object is ready   3m36s

Connect to the cluster with the kubeconfig#

  1. View the status of the applied MkeChildConfig to obtain the name of the secret that contains the kubeconfig:

    kubectl -n k0rdent get mkechildconfig my-mke-child -o yaml

    Example status, with secret:

    status:
  clusterID: kube-system:20d005f3-d8c5-4c88-a8d9-7e97e6a1a8ca
  kubeConfigSecret: my-mke-child-kubeconfig
  licenseStatus:
    licenseType: unlicensed

  2. Get the kubeconfig and use it to connect to the child cluster:

    kubectl -n k0rdent get secret my-mke-child-kubeconfig -o jsonpath='{ .data.value }' | base64 -d > kubeconfig.yaml

  3. Use the obtained kubeconfig to connect to the cluster:

    KUBECONFIG=kubeconfig.yaml kubectl get no

    Example output:

    NAME                                        STATUS   ROLES           AGE    VERSION
ip-172-31-0-32.us-east-2.compute.internal   Ready    control-plane   3h5m   v1.32.6+k0s
ip-172-31-0-49.us-east-2.compute.internal   Ready    <none>          3h5m   v1.32.6+k0s
...

Access the child cluster external address#

Retrieve the external address, which is the ingress of the child cluster. This is the address that you will use to interact with the child cluster.

  • To view the external address in short form, with the collumn in o-wide output:

    kubectl -n k0rdent get mkechildconfig my-mke-child -o wide

  • To read the external address from the resource status:

    kubectl -n k0rdent get mkechildconfig my-mke-child -o yaml

    In the resulting -o yaml file, the external address is the value of thestatus.externalAddress field.

Warning

  • If you decide to use the mkectl reset command to wipe the standalone MKE cluster that is serving as the management cluster, you must delete all the existing child clusters as otherwise they will remain in an orphaned state.

  • Currently, MkeChildConfig objects can only be applied to the k0rdent namespace.