Spec Generator Utility - User Guide

Overview #

The Spec Generator Utility reduces the risk of configuration errors when importing managed Kubernetes clusters into the Kosmos system.

When importing clusters—such as Amazon EKS, Google GKE, Azure AKS, or SPC MKS — critical specifications (for example, node groups) may be incorrectly defined. Misconfigurations can result in unintended updates or disruptions to the target cluster.

This utility automatically extracts metadata and configuration details from your existing managed Kubernetes cluster and generates an accurate, ready-to-use cluster specification file. The generated spec can then be safely imported into the XYZ system.

How to use #

Command syntax #

$ python3 import-helper-tool.py [-h] --type {eks,gke,mks,aks} --cluster-name CLUSTER-NAME --fleet FLEET
[--eks-profile EKS-PROFILE]
[--eks-region EKS-REGION]
[--eks-kosmos-role-arn EKS-KOSMOS-ROLE-ARN]
[--gke-cluster-region GKE-CLUSTER-REGION]
[--gke-service-account GKE-SERVICE-ACCOUNT]
[--gke-workload-identity-pool GKE-WORKLOAD-IDENTITY-POOL]
[--gke-workload-identity-provider GKE-WORKLOAD-IDENTITY-PROVIDER]
[--gke-project-id GKE-PROJECT-ID]
[--aks-cluster-resource-group AKS-CLUSTER-RESOURCE-GROUP]
[--aks-client-name AKS-CLIENT-NAME]
[--aks-client-resource-group AKS-CLIENT-RESOURCE-GROUP]
[--mks-region MKS-REGION]
[--mks-kosmos-role-arn MKS-KOSMOS-ROLE-ARN]
[--mks-profile MKS-PROFILE]

Requirements:

• Python 3 must be installed on your system.

• The following parameters are required for all cluster types:

  • --type
  • --cluster-name
  • --fleet

Supported cloud service providers (CSPs) #

Parameter explanation #

Prerequisites #

AWS EKS #

• Existing EKS cluster to be imported

• IAM role for Kosmos

• Valid credentials with at least:

  eks:Get*
  eks:List*
  eks:Describe*
  

GCP GKE #

• Existing GKE cluster to be imported
• IAM prerequisites for Kosmos (can be created manually or via the terraform-kosmos-gke-identity module)

• Valid credentials with at least:

  container.clusters.get
  container.clusters.list
  resourcemanager.projects.get
  

Azure AKS #

• Existing AKS cluster to be imported
• IAM prerequisites for Kosmos (can be created manually or via the terraform-kosmos-aks-identity module)

• Valid credentials with at least:

  Microsoft.ContainerService/managedClusters/read
  Microsoft.ManagedIdentity/userAssignedIdentities/read
  

SPC MKS #

• Existing MKS cluster to be imported

• IAM role for Kosmos

• Valid credentials with at least:

  eks:Get*
  eks:List*
  eks:Describe*
  

Example usage #

You can download the kosmos_import_helper.py utility using the link provided below and save it to your local machine.

Download kosmos_import_helper.py

Once downloaded, ensure the file is accessible from your working directory before running it with:

python3 kosmos_import_helper.py --help

This will verify that the script is correctly downloaded and ready to use.

AWS EKS example #

python3 kosmos_import_helper.py \
  --type eks \
  --cluster-name <EKS_CLUSTER_NAME> \
  --fleet <FLEET_NAME> \
  --eks-profile <AWS_PROFILE> \
  --eks-region <AWS_REGION> \
  --eks-kosmos-role-arn <KOSMOS_ROLE_ARN>

Example:

python3 kosmos_import_helper.py \
  --type eks \
  --cluster-name my-eks-cluster \
  --fleet production-fleet \
  --eks-profile scop \
  --eks-region ap-southeast-1 \
  --eks-kosmos-role-arn arn:aws:iam::123456789012:role/kosmos-role

GCP GKE example #

python3 kosmos_import_helper.py \
  --type gke \
  --cluster-name <GKE_CLUSTER_NAME> \
  --fleet <FLEET_NAME> \
  --gke-workload-identity-pool <WORKLOAD_IDENTITY_POOL> \
  --gke-workload-identity-provider <WORKLOAD_IDENTITY_PROVIDER> \
  --gke-cluster-region <GCP_REGION> \
  --gke-service-account <SERVICE_ACCOUNT_EMAIL> \
  --gke-project-id <GCP_PROJECT_ID>

Example:

python3 kosmos_import_helper.py \
  --type gke \
  --cluster-name my-gke-cluster \
  --fleet production-fleet \
  --gke-workload-identity-pool kosmos-prd \
  --gke-workload-identity-provider kosmos-prd-provider \
  --gke-cluster-region asia-southeast1 \
  --gke-service-account kosmos-account@project123.iam.gserviceaccount.com \
  --gke-project-id project123

Azure AKS example #

python3 kosmos_import_helper.py \
  --type aks \
  --cluster-name <AKS_CLUSTER_NAME> \
  --fleet <FLEET_NAME> \
  --aks-cluster-resource-group <AKS_CLUSTER_RESOURCE_GROUP> \
  --aks-client-name <AZURE_AD_CLIENT_NAME> \
  --aks-client-resource-group <AZURE_AD_CLIENT_RESOURCE_GROUP>

Example:

python3 kosmos_import_helper.py \
  --type aks \
  --cluster-name my-aks-cluster \
  --fleet production-fleet \
  --aks-cluster-resource-group MyResourceGroup \
  --aks-client-name clientName \
  --aks-client-resource-group ClientResourceGroup

SPC MKS example #

python3 kosmos_import_helper.py \
  --type mks \
  --cluster-name <MKS_CLUSTER_NAME> \
  --fleet <FLEET_NAME> \
  --mks-profile <SPC_PROFILE> \
  --mks-region <SPC_REGION> \
  --mks-kosmos-role-arn <KOSMOS_ROLE_ARN>

Example:

python3 kosmos_import_helper.py \
  --type mks \
  --cluster-name my-mks-cluster \
  --fleet production-fleet \
  --mks-profile scop-spc \
  --mks-region ap-southeast-1 \
  --mks-kosmos-role-arn arn:aws:iam::123456789012:role/kosmos-role

Outputs #

After execution, the tool generates a cluster specification file compatible with Kosmos. The file contains the exact configuration and metadata of your existing managed cluster.

You can import the cluster:

• Through the Kosmos console
• Or via CLI:

kosmos create [eks|gke|mks|aks] --fleet $FLEET_NAME -f $PATH_TO_FILE

Example output – EKS #

apiVersion: storage.kosmos.spcplatform.com/v1
kind: EKSCluster
metadata:
  name: my-eks-cluster
  namespace: production-fleet
spec:
  eksConfig:
    displayName: my-eks-cluster
    imported: true
    kosmosRoleArn: arn:aws:iam::123456789012:role/kosmos-role

Example output – GKE #

apiVersion: storage.kosmos.spcplatform.com/v1
kind: GKECluster
metadata:
  name: my-gke-cluster
  namespace: production-fleet
spec:
  gkeConfig:
    clusterAddons:
      horizontalPodAutoscaling: true
      httpLoadBalancing: true

Example output – MKS #

apiVersion: storage.kosmos.spcplatform.com/v1
kind: MKSCluster
metadata:
  name: my-mks-cluster
  namespace: production-fleet
spec:
  mksConfig:
    displayName: my-mks-cluster
    imported: true
    kosmosRoleArn: arn:aws:iam::123456789012:role/kosmos-role

Example output – AKS #

apiVersion: storage.kosmos.spcplatform.com/v1
kind: AKSCluster
metadata:
  name: my-aks-cluster
  namespace: production-fleet
spec:
  aksConfig:
    authorizedIpRanges: null
    httpApplicationRouting: false
    kubernetesVersion: "1.32"

Troubleshooting and tips #

• Ensure you have sufficient permissions to retrieve cluster metadata.
• Make sure your CLI is authenticated with the respective CSP (AWS, GCP, Azure, or SPC).
• If errors occur, verify parameter values and review logs for detailed diagnostics.

Edit this page on GitHub