Skip to content

Getting started

In a nutshell

  1. Deploy ORC to your Kubernetes cluster
  2. Create a Kubernetes secret containing a clouds.yaml
  3. Deploy your OpenStack infrastructure as Kubernetes custom resources

Deploy ORC to your Kubernetes cluster

From a fresh checkout of the git repository, from the main branch, run:

make deploy IMG=quay.io/orc/openstack-resource-controller:branch-main

Create a Kubernetes secret containing a clouds.yaml

kubectl create secret generic openstack-clouds \
    --from-file=clouds.yaml=${XDG_CONFIG_HOME:-~/.config}/openstack/clouds.yaml

Note

The command above will upload your entire clouds.yaml to your Kubernetes cluster! If that is not appropriate, you may want to upload a slimmed version of it.

Deploy your OpenStack infrastructure as Kubernetes custom resources

This is the definition of a subnet. You can apply it to your cloud:

kubectl apply --server-side -f- <<EOF
apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Subnet
metadata:
  labels:
    app.kubernetes.io/name: openstacksubnet
    app.kubernetes.io/instance: openstacksubnet-gettingstarted
    app.kubernetes.io/part-of: gettingstarted
  name: subnet-1
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: managed
  networkRef: network-1
  resource:
    description: |
      Example subnet
    tags:
    - gettingstarted
    ipVersion: 4
    allocationPools:
    - start: 192.168.1.5
      end: 192.168.1.60
    cidr: 192.168.1.0/24
EOF

The controller will only attempt creating the subnet when the corresponding Network exists:

$ kubectl get subnets
NAME       ID    AVAILABLE   MESSAGE                                       AGE
subnet-1         False       Waiting for Network/network-1 to be created   4s

Let's create it:

kubectl apply --server-side -f- <<EOF
apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Network
metadata:
  labels:
    app.kubernetes.io/name: openstacknetwork
    app.kubernetes.io/instance: openstacknetwork-gettingstarted
    app.kubernetes.io/part-of: gettingstarted
  name: network-1
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: managed
  resource:
    description: |
      Example network
    tags:
    - gettingstarted
EOF

After a few seconds, both resources become ready:

$ kubectl get networks
NAME        ID                                     AVAILABLE   MESSAGE                           AGE
network-1   5df739fb-2cdf-4d49-ad67-95fd36d99056   True        OpenStack resource is available   96s

$ kubectl get subnets
NAME       ID                                     AVAILABLE   MESSAGE                           AGE
subnet-1   bb1f0b74-0e79-4f77-b518-6a05a61662f0   True        OpenStack resource is available   2m42s

The subnet can be inspected through its Kubernetes representation, under .status.resource:

kubectl get subnet subnet-1 -o yaml

apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Subnet
metadata:
  annotations:
  creationTimestamp: "2025-01-03T16:29:05Z"
  finalizers:
  - openstack.k-orc.cloud/port
  - openstack.k-orc.cloud/subnet
  generation: 1
  labels:
    app.kubernetes.io/instance: openstacksubnet-gettingstarted
    app.kubernetes.io/name: openstacksubnet
    app.kubernetes.io/part-of: gettingstarted
  name: subnet-1
  namespace: default
  resourceVersion: "2318"
  uid: cc132c51-990d-4b4e-be80-3b72822d1a88
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: managed
  networkRef: network-1
  resource:
    allocationPools:
    - end: 192.168.1.60
      start: 192.168.1.5
    cidr: 192.168.1.0/24
    description: |
      Example subnet
    ipVersion: 4
    tags:
    - gettingstarted
status:
  conditions:
  - lastTransitionTime: "2025-01-03T16:34:31Z"
    message: OpenStack resource is available
    observedGeneration: 1
    reason: Success
    status: "True"
    type: Available
  - lastTransitionTime: "2025-01-03T16:34:31Z"
    message: OpenStack resource is up to date
    observedGeneration: 1
    reason: Success
    status: "False"
    type: Progressing
  id: bb1f0b74-0e79-4f77-b518-6a05a61662f0
  resource:
    allocationPools:
    - end: 192.168.1.60
      start: 192.168.1.5
    cidr: 192.168.1.0/24
    description: |
      Example subnet
    dnsPublishFixedIP: false
    enableDHCP: true
    gatewayIP: 192.168.1.1
    ipVersion: 4
    ipv6AddressMode: ""
    ipv6RAMode: ""
    name: subnet-1
    projectID: c73b7097d07c46f78eb4b4dcfbac5ca8
    revisionNumber: 1
    tags:
    - gettingstarted

Reset

To reset both Kubernetes and Openstack to their original state, delete the resources and undeploy ORC:

kubectl delete subnet subnet-1
kubectl delete network network-1
kubectl delete secret openstack-clouds
make undeploy