Crossplane Provider for Oracle Cloud Infrastructure

crossplane-provider-oci is a Crossplane provider for Oracle Cloud Infrastructure (OCI) that is built using Upjet code generation tools.

Upjet creates XRM-conformant managed resources for the OCI APIs based on OCI Terraform Resources.

Requirements

Software and Tools

• Git 2.25 (recommended)
• Terraform 1.4.6 (recommended)
• Go 1.19.x (required)
• Goimports
• Kubectl 5.0.1 (recommended)
• Helm 3.11.2 (recommended)
• Docker 20.10.20 (recommended)
• Kubernetes cluster 1.25.3 (recommended)
  • OCI Container Engine for Kubernetes (Oracle's Kubernetes offering)
  • Rancher Desktop (for local development)
• Crossplane 1.10 (recommended)

Configurations

Before building the provider, ensure the following items are already set up in your system:

• The $PATH environment variable contains paths for the preceding software binaries.
• The GOPATH variable is set properly. (Example: export GOPATH=~/go/19.1.6)
• A Kubernetes cluster is running locally, and the correct Kubernetes context is selected.

Install Crossplane

Crossplane installs on top of Kubernetes. Install Crossplane onto a Kubernetes cluster using the following steps.

1. Create a namespace for Crossplane.

   $ kubectl create namespace crossplane-system

2. Add a Helm repository for Crossplane.

   $ helm repo add crossplane-stable https://charts.crossplane.io/stable

3. Update the Helm repository.

   $ helm repo update

4. Install Crossplane.

   $ helm install crossplane --namespace crossplane-system crossplane-stable/crossplane

5. Verify that Crossplane is deployed.

   $ helm list -n crossplane-system

6. Check for components installed as part of Crossplane on Kubernetes.

   $ kubectl get all -n crossplane-system

Install the Crossplane kubectl Plugin

$ curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | sh
$ mv kubectl-crossplane ~/.rd/bin

Clone crossplane-provider-oci

1. Clone the repository to $GOPATH/src/github.com/crossplane-providers/crossplane-provider-oci.

   $ mkdir -p $GOPATH/src/github.com/crossplane-providers; cd $GOPATH/src/github.com/crossplane-providers
   $ git clone [email protected]:oracle-samples/crossplane-provider-oci.git

2. Change to the provider directory.

   $ cd $GOPATH/src/github.com/crossplane-providers/crossplane-provider-oci

Install and run the OCI Crossplane Provider

Install and run OCI Crossplane provider locally or on a Kubernetes cluster. Running the Crossplane provider locally gives more flexibility for debugging and development.

Install and Run the Provider Locally

Use these commands to set up and configure an OCI Crossplane provider on your local Kubernetes cluster in your tenancy.

1. Generate the crossplane resource definitions (CRD).

   $ make generate

2. Register the CRDs with your locally running Kubernetes cluster.

   $ kubectl apply -f package/crds

3. On a different terminal, to ensure it will run in the background, start crossplane-provider-oci on your Kubernetes cluster.

   $ make run

   Note: You might be prompted if you want the provider application to accept incoming network connections. Click Allow.

Install and Run the Provider on Container Engine for Kubernetes

Build the Provider

1. Create package for all the archetypes defined, the package will be available in _output/xpkg directory.

   $ cd $GOPATH/src/github.com/crossplane-providers/crossplane-provider-oci
   $ make build.all

Create a Container Engine Cluster

1. Log into your OCI console and create a Container Engine cluster as mentioned in the OCI documentation.
2. After the cluster is created, you can access the cluster from your local Kubernetes client (kubectl). Follow the instructions in the OCI Documentation.

Upload the Package into OCIR (OCI Registry)

1. Create a repository following the instructions provided in this Oracle Documentation Creating a Repository.
2. Follow the instructions in the Oracle documentation Pushing Images Using the Docker CLI to push the package file to the registry.
3. Generate an authorization token for the user from the OCI console.
4. Log into the container registry from Docker. Enter the username in the format \<tenancy-namespace>/\<username> and the authorization token generated in the previous step is the password.

   $ docker login <regionCode>.ocir.io

5. Go to the package directory.

   $ cd $GOPATH/src/github.com/crossplane-providers/crossplane-provider-oci/_output/xpkg/linux_amd64

6. Push the package into OCIR using the Crossplane kubectl plugin.

   $ kubectl crossplane push provider <regionCode>.ocir.io/<tenancy-namespace>/<repositoryName>:<version>

Create an OCIR Secret

When installing the Crossplane provider, the OCI Container Engine needs to pull in the image, which is uploaded in the OCI Registry.

1. Use this kubectl command, as described in the OCI Documentation, to create a secret:

   $ kubectl create secret docker-registry <ocir-secret-name> --namespace crossplane-system --docker-server=<region-key>.ocir.io --docker-username='<tenancy-namespace>/<oci-username>' --docker-password='<oci-auth-token>' --docker-email='<email-address>'

Install Crossplane Provider for OCI

Refer to the image pushed in the previous step and run this command to install the Crossplane provider.

$ cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: crossplane-provider-oci
spec:
package: <regionCode>.ocir.io/<namespace>/<repositoryName>:<version>
packagePullSecrets:
  - name: <ocir-secret-name>
EOF

Verify Installation of the Provider

kubectl get crossplane

Configure the OCI Crossplane Provider

For the provider to communicate with the Oracle Cloud Infrastructure, we need to apply some configuration.

1. Create a secret.yaml file using the template under examples/providerconfig/secret.yaml.tmpl. Fill in the respective values from your tenancy and register it with Kubernetes.

   $ kubectl apply -f examples/providerconfig/secret.yaml

   Note: Ensure that the values provided in the secret.yaml file are extracted in the same way as configuring the OCI CLI. Refer to the SDKConfig.

2. Register the provider configuration by running this command.

   $ kubectl apply -f examples/providerconfig/providerconfig.yaml

   Note: Modify the examples/providerconfig/providerconfig.yaml file, if the secret name registered is different than what is provided in the template.

At this stage, we have our OCI Crossplane provider configured to work with your tenancy.

Example: Creating an Object Storage Bucket

1. Use this command to instruct Crossplane to create the bucket in the OCI tenancy using Terraform.

   # Edit examples/objectstorage/bucket.yaml with your compartment and storage name space as documented.
   # Apply the example that creates an Object Storage bucket
   $ kubectl apply -f examples/objectstorage/bucket.yaml

2. Verify the status of the resource by running this command (example output is shown).

   $ kubectl get managed
   NAME                                                         READY   SYNCED   EXTERNAL-NAME              AGE
   bucket.objectstorage.oci.upbound.io/bucket-via-crossplane4   True    True     n/idimd1fghobk/b/bucket1   10m

   The Ready status True indicates that the resource creation is successful.

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide.

Security

Consult the security guide for our responsible security vulnerability disclosure process.

License

Copyright (c) 2022, 2023 Oracle and its affiliates.

Released under the Apache 2.0 license.