OpenMCF logoOpenMCF

Loading...

AliCloud KubernetesCluster

Deploys an Alibaba Cloud ACK Managed Kubernetes cluster with configurable CNI networking (Flannel or Terway), cluster addons, control plane logging, RRSA for pod-level IAM, and optional maintenance windows with automatic version upgrades. Worker nodes are managed separately through AliCloudKubernetesNodePool.

What Gets Created

When you deploy an AliCloudKubernetesCluster resource, OpenMCF provisions:

  • ACK Managed Kubernetes Cluster — an alicloud_cs_managed_kubernetes resource with a fully managed control plane (etcd, API server, controller manager, scheduler)
  • Cluster Addons — network CNI (Flannel or Terway), storage CSI drivers, and optional monitoring, logging, and ingress addons installed at creation time
  • API Server SLB — a public-facing SLB for the Kubernetes API server (when slbInternetEnabled is true)
  • NAT Gateway — auto-created for cluster VPC internet access (when newNatGateway is true)
  • RRSA OIDC Provider — RAM OIDC provider for pod-level IAM federation (when enableRrsa is true)

Prerequisites

  • Alibaba Cloud credentials configured via environment variables or OpenMCF provider config
  • At least two VSwitches in different Availability Zones within the same VPC
  • Non-overlapping CIDR ranges for the VPC, pod network, and service network
  • A NAT gateway if setting newNatGateway to false (nodes in private VSwitches need outbound internet access)
  • An SLS log project if configuring control plane logging with an external project

Quick Start

Create a file ack-cluster.yaml:

apiVersion: ali-cloud.openmcf.org/v1
kind: AliCloudKubernetesCluster
metadata:
  name: my-cluster
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AliCloudKubernetesCluster.my-cluster
spec:
  region: cn-hangzhou
  vswitchIds:
    - value: vsw-aaa111
    - value: vsw-bbb222
  podCidr: "172.20.0.0/16"
  serviceCidr: "172.21.0.0/20"
  addons:
    - name: flannel
    - name: csi-plugin
    - name: csi-provisioner

Deploy:

openmcf apply -f ack-cluster.yaml

This creates a standard-tier ACK cluster with Flannel CNI across two Availability Zones.

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
regionstringAlibaba Cloud region for the cluster (e.g., cn-hangzhou, us-west-1). Must match the region of the specified VSwitches.Required; non-empty
vswitchIdsStringValueOrRef[]VSwitch IDs for control plane and default worker node placement. Use VSwitches in distinct AZs for high availability.1–5 items required
vswitchIds[].valuestringDirect VSwitch ID value.—
vswitchIds[].valueFromobjectForeign key reference to an AliCloudVswitch resource.Default kind: AliCloudVswitch, field: status.outputs.vswitch_id
serviceCidrstringCIDR block for Kubernetes ClusterIP services. Must not overlap the VPC CIDR, pod CIDR, or node CIDR. Immutable after creation.Required; non-empty

Optional Fields

FieldTypeDefaultDescription
namestringmetadata.nameCluster name. 1–63 characters; must start with a letter or digit.
versionstringLatest stableKubernetes version (e.g., "1.28", "1.30").
clusterSpecstringack.standardCluster tier. ack.standard (free) or ack.pro.small (paid, enhanced SLA).
clusterDomainstringcluster.localKubernetes service discovery domain. Immutable after creation.
podCidrstring—Pod network CIDR for Flannel CNI. Required when using the flannel addon. Immutable.
podVswitchIdsStringValueOrRef[][]VSwitch IDs for pod ENI allocation with Terway CNI. Required when using terway-eniip.
proxyModestringipvskube-proxy mode: ipvs or iptables. Immutable after creation.
nodeCidrMaskint24Per-node pod CIDR mask size. Range: 24–28. A /24 gives ~253 pods per node. Immutable.
newNatGatewaybooltrueWhether ACK auto-creates a NAT gateway. Set to false when managing your own AliCloudNatGateway.
slbInternetEnabledbooltrueWhether to create a public SLB for the Kubernetes API server.
securityGroupIdStringValueOrRefAuto-createdSecurity group for cluster nodes. Can reference an AliCloudSecurityGroup via valueFrom.
isEnterpriseSecurityGroupboolfalseAuto-create an advanced security group (65,536 rules, 100,000 ENIs). Conflicts with securityGroupId.
enableRrsaboolfalseEnable RRSA for pod-level IAM via OIDC federation. Cannot be disabled once enabled.
deletionProtectionboolfalsePrevent accidental cluster deletion via the API.
encryptionProviderKeyStringValueOrRef—KMS key ID for encrypting Kubernetes Secrets at rest. Immutable. Can reference AliCloudKmsKey.
customSanstring—Additional SANs for the API server TLS certificate (comma-separated IPs or domains).
addonsAliCloudKubernetesAddon[][]Addons to install at creation time. See addon fields below.
addons[].namestring—Addon identifier (e.g., flannel, terway-eniip, csi-plugin). Required.
addons[].configstring—JSON-encoded addon configuration.
addons[].versionstringDefault for K8s versionAddon version override.
addons[].disabledboolfalseRegister but do not install the addon.
loggingobject—Control plane and audit logging configuration.
logging.controlPlaneLogProjectStringValueOrRefAuto-createdSLS project for control plane logs. Can reference AliCloudLogProject.
logging.controlPlaneLogTtlstring"30"Log retention in days.
logging.controlPlaneLogComponentsstring[][]Components to log: apiserver, kcm, scheduler, ccm, controlplane-events, alb, coredns.
logging.auditLogEnabledboolfalseEnable Kubernetes audit logging.
logging.auditLogSlsProjectstringSame as control planeSeparate SLS project for audit logs.
maintenanceWindowobject—Maintenance window for controlled patching.
maintenanceWindow.enablebool—Whether the window is active.
maintenanceWindow.maintenanceTimestring—Start time in RFC 3339 format.
maintenanceWindow.durationstring—Window duration (e.g., "3h").
maintenanceWindow.weeklyPeriodstringThursdayDay(s) of the week (e.g., "Monday,Thursday").
autoUpgradeobject—Automatic version upgrade policy. Requires a maintenance window.
autoUpgrade.enabledbool—Whether auto-upgrade is active.
autoUpgrade.channelstringpatchUpgrade channel: patch, stable, or rapid.
tagsmap<string, string>{}Tags applied to the cluster and auto-created resources.
resourceGroupIdstringDefault groupAlibaba Cloud resource group for organizational grouping.
timezonestring—IANA timezone for cluster nodes (e.g., "Asia/Shanghai").

Examples

Development Cluster with Flannel

A minimal cluster for development and testing.

apiVersion: ali-cloud.openmcf.org/v1
kind: AliCloudKubernetesCluster
metadata:
  name: dev-cluster
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AliCloudKubernetesCluster.dev-cluster
spec:
  region: cn-hangzhou
  vswitchIds:
    - value: vsw-aaa111
    - value: vsw-bbb222
  podCidr: "172.20.0.0/16"
  serviceCidr: "172.21.0.0/20"
  addons:
    - name: flannel
    - name: csi-plugin
    - name: csi-provisioner

Terway Cluster with Pod-Level IAM

A staging cluster using ENI-based networking with RRSA and control plane logging.

apiVersion: ali-cloud.openmcf.org/v1
kind: AliCloudKubernetesCluster
metadata:
  name: staging-cluster
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: staging.AliCloudKubernetesCluster.staging-cluster
spec:
  region: cn-shanghai
  clusterSpec: ack.pro.small
  version: "1.30"
  vswitchIds:
    - value: vsw-node-a
    - value: vsw-node-b
  podVswitchIds:
    - value: vsw-pod-a
    - value: vsw-pod-b
  serviceCidr: "172.21.0.0/20"
  enableRrsa: true
  newNatGateway: false
  addons:
    - name: terway-eniip
    - name: csi-plugin
    - name: csi-provisioner
    - name: arms-prometheus
    - name: metrics-server
  logging:
    controlPlaneLogProject:
      value: staging-logs
    controlPlaneLogComponents:
      - apiserver
      - kcm
      - scheduler
    auditLogEnabled: true
  tags:
    team: platform
    env: staging

Production Cluster with Full Security and Lifecycle

A production-grade cluster with Secrets encryption, maintenance windows, auto-upgrade, and deletion protection.

apiVersion: ali-cloud.openmcf.org/v1
kind: AliCloudKubernetesCluster
metadata:
  name: prod-cluster
  org: acme-corp
  env: production
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: acme-corp
    pulumi.openmcf.org/project: infrastructure
    pulumi.openmcf.org/stack.name: production.AliCloudKubernetesCluster.prod-cluster
spec:
  region: cn-hangzhou
  name: acme-prod-ack
  clusterSpec: ack.pro.small
  version: "1.30"
  vswitchIds:
    - value: vsw-node-a
    - value: vsw-node-b
    - value: vsw-node-c
  podVswitchIds:
    - value: vsw-pod-a
    - value: vsw-pod-b
    - value: vsw-pod-c
  serviceCidr: "172.21.0.0/20"
  proxyMode: ipvs
  nodeCidrMask: 26
  newNatGateway: false
  slbInternetEnabled: true
  securityGroupId:
    value: sg-prod-ack
  enableRrsa: true
  deletionProtection: true
  encryptionProviderKey:
    value: kms-prod-key-id
  addons:
    - name: terway-eniip
    - name: csi-plugin
    - name: csi-provisioner
    - name: logtail-ds
      config: '{"IngressDashboardEnabled":"true","sls_project_name":"acme-prod-logs"}'
    - name: arms-prometheus
    - name: metrics-server
    - name: ack-node-problem-detector
  logging:
    controlPlaneLogProject:
      value: acme-prod-logs
    controlPlaneLogTtl: "90"
    controlPlaneLogComponents:
      - apiserver
      - kcm
      - scheduler
      - ccm
      - controlplane-events
    auditLogEnabled: true
    auditLogSlsProject: acme-prod-audit
  maintenanceWindow:
    enable: true
    maintenanceTime: "2026-03-01T03:00:00+08:00"
    duration: "3h"
    weeklyPeriod: Wednesday
  autoUpgrade:
    enabled: true
    channel: patch
  tags:
    team: platform
    cost-center: infra-001
  resourceGroupId: rg-acme-prod
  timezone: Asia/Shanghai

Using Foreign Key References

Reference other OpenMCF-managed resources instead of hardcoding IDs:

apiVersion: ali-cloud.openmcf.org/v1
kind: AliCloudKubernetesCluster
metadata:
  name: ref-cluster
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AliCloudKubernetesCluster.ref-cluster
spec:
  region: cn-hangzhou
  vswitchIds:
    - valueFrom:
        kind: AliCloudVswitch
        name: node-vsw-a
        field: status.outputs.vswitch_id
    - valueFrom:
        kind: AliCloudVswitch
        name: node-vsw-b
        field: status.outputs.vswitch_id
  podVswitchIds:
    - valueFrom:
        kind: AliCloudVswitch
        name: pod-vsw-a
        field: status.outputs.vswitch_id
    - valueFrom:
        kind: AliCloudVswitch
        name: pod-vsw-b
        field: status.outputs.vswitch_id
  serviceCidr: "172.21.0.0/20"
  securityGroupId:
    valueFrom:
      kind: AliCloudSecurityGroup
      name: ack-sg
      field: status.outputs.security_group_id
  encryptionProviderKey:
    valueFrom:
      kind: AliCloudKmsKey
      name: ack-kms-key
      field: status.outputs.key_id
  enableRrsa: true
  addons:
    - name: terway-eniip
    - name: csi-plugin
    - name: csi-provisioner
  logging:
    controlPlaneLogProject:
      valueFrom:
        kind: AliCloudLogProject
        name: platform-logs
        field: status.outputs.project_name
    auditLogEnabled: true

Stack Outputs

After deployment, the following outputs are available in status.outputs:

OutputTypeDescription
cluster_idstringACK cluster ID assigned by Alibaba Cloud
cluster_namestringCluster name as created
api_server_internetstringPublic API server endpoint (empty when slbInternetEnabled is false)
api_server_intranetstringPrivate (VPC-internal) API server endpoint
vpc_idstringVPC ID computed from the provided VSwitches
security_group_idstringSecurity group ID used by cluster nodes (user-provided or auto-created)
nat_gateway_idstringNAT gateway ID (empty when newNatGateway is false)
worker_ram_role_namestringRAM role name attached to worker nodes
rrsa_oidc_issuer_urlstringRRSA OIDC issuer URL for pod IAM trust policies (empty when enableRrsa is false)
ram_oidc_provider_namestringRRSA OIDC provider name in RAM (empty when enableRrsa is false)
ram_oidc_provider_arnstringRRSA OIDC provider ARN (empty when enableRrsa is false)

Related Components

  • AliCloudVpc — provides the VPC for cluster networking
  • AliCloudVswitch — provides VSwitches for node and pod placement
  • AliCloudSecurityGroup — controls inbound and outbound traffic for cluster nodes
  • AliCloudNatGateway — provides outbound internet access for nodes in private VSwitches
  • AliCloudKmsKey — provides the encryption key for Kubernetes Secrets at rest
  • AliCloudLogProject — provides the SLS project for control plane and audit logs
  • AliCloudKubernetesNodePool — manages worker node pools within this cluster

Next article

AliCloud KubernetesNodePool

AliCloud KubernetesNodePool Deploys a worker node pool in an Alibaba Cloud ACK Managed Kubernetes cluster with configurable instance types, ESSD disk configuration, auto-scaling, managed lifecycle (auto-repair, auto-upgrade), spot instance support, and Kubernetes scheduling properties (labels, taints). What Gets Created When you deploy an AliCloudKubernetesNodePool resource, OpenMCF provisions: ACK Node Pool — an alicloudcskubernetesnodepool resource containing a group of ECS worker nodes with...
Read next article
Presets
3 ready-to-deploy configurationsView presets →