Skip to main content
Version: 0.7

Use Crossplane (Alpha)

caution

This is currently an experimental feature. We do not recommend you use this for production purposes. We're working on expanding the supported services to add more AWS services, and to include Azure and GCP support.

Crossplane lets you provision cloud infrastructure using the Kubernetes API. Using Crossplane, you can define the resources or backing services your application needs from your cloud provider.

Kore automatically installs and enables Crossplane in AWS EKS clusters by default (but you can disable it). Kore also sets up an AWS provider for an EKS cluster. The kore Administrator does not need to do any additional configuration.

This section gives examples for how to provision the currently supported cloud services on an AWS EKS cluster you've configured in Kore.

For more information, see:

Supported clusters and services for Crossplane#

Currently, Kore supports the following cluster type and cloud services with Crossplane:

Cluster typeAWS EKS clusters
Cloud services

Create a namespace in your cluster#

To provision one of the supported cloud services, you apply a .yaml file that defines the resource in your namespace.

To create a namespace:

  1. In the Kore portal Team UI, navigate to Clusters.
  2. Click the cluster, and then click New namespace.
  3. For this example, enter the name test.
  4. Click Create namespace

CLI alternative: kore create namespace test --cluster YOUR_CLUSTER_NAME

Create an S3 bucket instance#

This example uses the namespace test that you created above. The connection parameters to the S3 bucket instance are created in a Kubernetes secret you specify in the file below. See Connect to the S3 bucket below for details.

To create an S3 bucket instance:

  1. Apply the following .yaml file:

    cat <<EOF | kubectl apply -f -apiVersion: aws.crossplane.kore.appvia.io/v1alpha1kind: S3BucketInstancemetadata:  namespace: test  name: s3-bucket-testspec:  parameters:    deletionPolicy: Delete    name: kore-andras-crossplane-test    region: eu-west-2    versioningConfiguration:      status: Enabled  writeConnectionSecretToRef:    name: s3-bucket-testEOF
  2. Check the status of the S3 bucket instance:

    kubectl -n test get S3BucketInstance s3-bucket-testNAME             READY   CONNECTION-SECRET   AGEs3-bucket-test   False   s3-bucket-test      6s

    When the READY column changes to True, the service is ready to be used.

  3. (Optional) Check Kubernetes events for any errors:

    kubectl -n test get events

Available parameters for your S3 bucket instance#

For available parameters, see AWS S3 Bucket.

Connect to the S3 bucket#

The connection parameters for this S3 bucket instance are written to a Kubernetes secret called s3-bucket-test in the test namespace. The secret contains the following keys:

  • awsAccessKeyID
  • awsSecretAccessKey
  • bucketName
  • region

The secret can be consumed in a Kubernetes pod as environment variables or through a file in a volume mounted on its container(s).

Example: Below is a Kubernetes Job using the secret as environment variables to list the AWS S3 Bucket.

cat <<EOF | kubectl apply -f -apiVersion: batch/v1kind: Jobmetadata:  namespace: test  name: s3-bucket-connection-testspec:  ttlSecondsAfterFinished: 100  template:    spec:      containers:      - name: kore-secret-env        env:          - name: AWS_ACCESS_KEY_ID            valueFrom:              secretKeyRef:                name: s3-bucket-test                key: awsAccessKeyID          - name: AWS_SECRET_ACCESS_KEY            valueFrom:              secretKeyRef:                name: s3-bucket-test                key: awsSecretAccessKey          - name: AWS_S3_BUCKET_NAME            valueFrom:              secretKeyRef:                name: s3-bucket-test                key: bucketName          - name: AWS_DEFAULT_REGION            valueFrom:              secretKeyRef:                name: s3-bucket-test                key: region        image: amazon/aws-cli        command: ["sh"]        args:          - -e          - -c          - |            echo "Listing the \$(AWS_S3_BUCKET_NAME) bucket"            aws s3 ls --summarize s3://\$(AWS_S3_BUCKET_NAME)/      restartPolicy: NeverEOF

Delete the S3 bucket instance#

Object deletion is instantaneous. The external services are deleted in the background if in your S3 bucket creation file deletionPolicy is set to Delete.

To delete the S3 bucket instance:

  1. Run kubectl -n test delete S3BucketInstance s3-bucket-test.

    caution

    If the S3 bucket has objects, the deletion fails. Crossplane does not delete any existing objects—you must delete them manually.

  2. (Optional) Check the Kubernetes events for any errors:

    kubectl -n test get events

  3. (Optional) As a cluster admin you can check to see if there are any lingering service objects:

    kubectl get managed

Create a PostgreSQL database instance#

This example uses the namespace test that you created above.

To create a PostgreSQL database instance:

  1. Apply the following .yaml file:

    cat <<EOF | kubectl apply -f -apiVersion: aws.crossplane.kore.appvia.io/v1alpha1kind: PostgreSQLDatabaseInstancemetadata:  namespace: test  name: postgres-testspec:  parameters:    allocatedStorage: 5    deletionPolicy: Delete    engineVersion: "12.4"    finalDBSnapshotIdentifier: postgres-test-final-snapshot  writeConnectionSecretToRef:    name: postgres-testEOF
  2. Check the status of the PostgreSQL instance:

    kubectl -n test get PostgreSQLDatabaseInstance postgres-testNAME            READY   CONNECTION-SECRET   AGEpostgres-test   False   postgres-test       6s

    It can take more than 10 minutes for a PostgreSQL database instance to be provisioned. When the READY column changes to True, the service is ready to be used.

  3. (Optional) Check Kubernetes events for any errors:

    kubectl -n test get events

Available parameters for the PostreSQL database instance#

For available parameters, see AWS RDS PostgreSQL Database.

Connect to the PostgreSQL database instance#

The connection parameters are written to a Kubernetes secret called postgres-test in the test namespace. The secret contains the following keys:

  • endpoint
  • port
  • username
  • password
warning

The connection parameters contain the master username and password which is a security risk. We are working on solving this as soon as possible.

You can use the secret with the above keys in a Kubernetes job to connect to the PostgreSQL database instance, as shown in this example:

apiVersion: batch/v1kind: Jobmetadata:  namespace: test  name: postgres-connection-testspec:  ttlSecondsAfterFinished: 60  template:    spec:      containers:      - name: postgres        env:          - name: PGHOST            valueFrom:              secretKeyRef:                name: postgres-test                key: endpoint          - name: PGPORT            valueFrom:              secretKeyRef:                name: postgres-test                key: port          - name: PGUSER            valueFrom:              secretKeyRef:                name: postgres-test                key: username          - name: PGPASSWORD            valueFrom:              secretKeyRef:                name: postgres-test                key: password        image: postgres:12-alpine        command: ["sh"]        args:          - -e          - -c          - |            echo "Connecting to \${PGHOST}:\${PGPORT} with user \${PGUSER}"            psql -d postgres -c "select now()"      restartPolicy: Never

Delete the PostgreSQL database instance#

Object deletion is instantaneous. The external services are deleted in the background if in your PostgreSQL creation file deletionPolicy is set to Delete.

To delete the PostgreSQL database instance:

  1. Run kubectl -n test delete PostgreSQLDatabaseInstance postgres-test.

  2. (Optional) Check the Kubernetes events for any errors:

    kubectl -n test get events

  3. (Optional) As a cluster admin you can check to see if there are any lingering service objects:

    kubectl get managed

Create a MySQL database instance#

This example uses the namespace test that you created above.

  1. Apply the following .yaml file:

    apiVersion: aws.crossplane.kore.appvia.io/v1alpha1kind: MySQLDatabaseInstancemetadata:  namespace: test  name: mysql-testspec:  parameters:    allocatedStorage: 5    deletionPolicy: Delete    engineVersion: "8.0"    multiAZ: false    finalDBSnapshotIdentifier: mysql-test-final-snapshot  writeConnectionSecretToRef:    name: mysql-test
  2. Check the status of the MySQL instance:

    kubectl -n test get MySQLDatabaseInstance mysql-testNAME            READY   CONNECTION-SECRET   AGEpostgres-test   False   mysql-test       6s

    It can take more than 10 minutes for a MySQL database instance to be provisioned. When the READY column changes to True, the service is ready to be used.

  3. (Optional) Check Kubernetes events for any errors:

    kubectl -n test get events

Available parameters for the MySQL database instance#

For available parameters, see AWS RDS MySQL Database.

Connect to the MySQL database instance#

The connection parameters are written to a Kubernetes secret called mysql-test in the test namespace. The secret contains the following keys:

  • endpoint
  • port
  • username
  • password
warning

The connection parameters contain the master username and password which is a security risk. We are working on solving this as soon as possible.

You can use the secret with the above keys in a Kubernetes job to connect to the MySQL database instance, as shown in this example:

apiVersion: batch/v1kind: Jobmetadata:  namespace: test  name: database-connection-testspec:  ttlSecondsAfterFinished: 60  template:    spec:      containers:      - name: mysql        env:          - name: HOST            valueFrom:              secretKeyRef:                name: mysql-test                key: endpoint          - name: PORT            valueFrom:              secretKeyRef:                name: mysql-test                key: port          - name: USERNAME            valueFrom:              secretKeyRef:                name: mysql-test                key: username          - name: PASSWORD            valueFrom:              secretKeyRef:                name: mysql-test                key: password        image: mysql:8        command: ["sh"]        args:          - -e          - -c          - |            echo "Connecting to \${HOST}:\${PORT} with user \${USERNAME}"            mysql -h "\${HOST}" -P "\${PORT}" -u "\${USERNAME}" --password="\${PASSWORD}" -e "select now()"      restartPolicy: Never

Delete the MySQL database instance#

Object deletion is instantaneous. The external services are deleted in the background if in your MySQL creation file deletionPolicy is set to Delete.

To delete the MySQL database instance:

  1. Run kubectl -n test delete MySQLDatabaseInstance mysql-test.

  2. (Optional) Check the Kubernetes events for any errors:

    kubectl -n test get events

  3. (Optional) As a cluster admin you can check to see if there are any lingering service objects:

    kubectl get managed

List all existing cloud service instances#

To list all existing cloud service instances:

  1. Run kubectl -n YOUR_NAMESPACE get claim

    A list of cloud service claims in the namespace you specified is returned.

Disable Crossplane in a cluster#

Crossplane is enabled by default in Kore clusters. If you don't want developers to be able to use Crossplane in a cluster, you must disable Crossplane in the cluster settings.

To disable Crossplane in a cluster:

  1. In the Kore UI Teams page, navigate to Clusters and click View on the cluster you want.
  2. Click the Settings tab, and then click the Edit button.
  3. In the Crossplane section, deselect Enabled.
  4. Click Save.

Troubleshoot as a team admin#

Team administrators can take the following steps to troubleshoot Crossplane issues.

Check health and status of Crossplane#

If Crossplane doesn't seem to work, try the following steps.

  1. Using the Kore CLI, check the crossplanedeployment object:

    kore -t TEAM_NAME get crossplanedeployment CLUSTER_NAMENAME           VERSION   CLUSTER        STATUS    AGECLUSTER_NAME   1.0.0     CLUSTER_NAME   Success   21h
    • If the object doesn't exist, Crossplane wasn't enabled for the cluster.
    • If the object has a status other than Success, inspect the object for error messages on the status sub-resource.
  2. Check for Kore services related to Crossplane:

    kore -t TEAM_NAME get service

    When Crossplane is installed successfully, the following Kore services should exist for a cluster:

    NAME                                   KIND                      PLAN                        STATUS     AGECLUSTER_NAME-crossplane                crossplane                crossplane-1.0.0            Success    21hCLUSTER_NAME-crossplane-aws-rds        crossplane-aws-rds        crossplane-aws-rds          Success    21hCLUSTER_NAME-crossplane-aws-s3         crossplane-aws-s3         crossplane-aws-s3           Success    21hCLUSTER_NAME-crossplane-provider-aws   aws-service-account-role  aws-service-account-role    Success    21h

    If any of these services have a status other than Success, inspect the object for error messages on the status sub-resource.

List all cloud service instance components#

Run these commands to list composites and managed resources:

  • kubectl get composite
  • kubectl get managed

List all Crossplane components#

Run this command:

kubectl get crossplane

Last updated on May 24, 2021