Cluster¶

The ghcr.io/captf-io/oci-cluster image implements the cluster role for a TerraformCluster on OCI. It creates the nodes’ network security groups, the API network load balancer and the control-plane nodes’ instance identity on the VCN you bring, and publishes the endpoint, the failure domains and the ids the machine and machinepool roles need.

What it creates¶

It lists the subnets and VCNs of the network compartment and picks the cluster’s by OCID, reads the region’s availability domains (and, in fault-domain mode, the fault domains), and reads the tenancy’s region subscriptions to find the home region, where IAM writes go. Every subnet must be found, AVAILABLE, in one VCN, and regional or in the control-plane subnet’s availability domain; these checks are preconditions, so a destroy skips them.

The node policy grants the dynamic group, in the cluster’s compartment, read instance-family, manage load-balancers, manage network-load-balancers and manage volume-family, plus use virtual-network-family in each network compartment. A statement about the root compartment reads in tenancy.

Inputs¶

Contract inputs used: captf_cluster (names), captf_tags, control_plane_endpoint (skips the load balancer) and cluster_network (api_server_port). captf_contract is validated; captf_object, kubernetes_version, control_plane_initialized and captf_cluster_outputs are declared and unused.

User variables, from variables.tf:

Outputs¶

An availability domain’s failure domain name is the part after its tenancy prefix (Uocm:US-ASHBURN-AD-1 becomes US-ASHBURN-AD-1), the zone the OCI cloud controller manager reports. Fault domains keep OCI’s names (FAULT-DOMAIN-1). An AD-specific control-plane subnet confines the cluster to the fault domains of its availability domain.

Health¶

With a user-supplied endpoint there is no load balancer to observe, and the cluster reports running.

Limitations¶

• The endpoint is fixed once the load balancer exists: the endpoint guard refuses any change to the inputs behind it (see API endpoint).
• The policy covers the compartment. Control-plane nodes can manage every load balancer and volume in it. Workers get no OCI permissions.
• The cloud controller manager needs no manage security-lists only with securityListManagementMode: None; open Service NodePorts with nodeport_allowed_cidrs.
• IAM changes propagate within minutes, so the first nodes may retry their first OCI calls.
• The dynamic group goes in the Default identity domain, through the classic IAM API.

Exceptions¶

• Two rules are open by default besides node-to-node traffic and the API port from the load balancer: ICMP type 3 code 4 from the VCN, so path MTU discovery works, and, with a user-supplied endpoint, the API backend ports from the VCN and api_allowed_cidrs, since that endpoint reaches the nodes directly.
• With the network gone, the network security groups carry a placeholder VCN id, because OpenTofu’s destroy still evaluates required arguments. Any other plan stops at the subnet checks first.

Example¶

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformCluster
metadata:
  name: demo
spec:
  source:
    image: ghcr.io/captf-io/oci-cluster:v0.1.0-opentofu
  identityRef:
    name: oci
  defaults:
    identityRef:
      name: oci
  variables:
    compartment_id: ocid1.compartment.oc1..<id>
    region: us-ashburn-1
    control_plane_subnet_id: ocid1.subnet.oc1.iad.<id>
    worker_subnet_id: ocid1.subnet.oc1.iad.<id>
    node_identity:
      defined_tag:
        namespace: captf
        key: cluster