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/v1alpha1
    kind: S3BucketInstance
    metadata:
    namespace: test
    name: s3-bucket-test
    spec:
    parameters:
    deletionPolicy: Delete
    name: kore-andras-crossplane-test
    region: eu-west-2
    versioningConfiguration:
    status: Enabled
    writeConnectionSecretToRef:
    name: s3-bucket-test
    EOF
  2. Check the status of the S3 bucket instance:

    kubectl -n test get S3BucketInstance s3-bucket-test
    NAME READY CONNECTION-SECRET AGE
    s3-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/v1
kind: Job
metadata:
namespace: test
name: s3-bucket-connection-test
spec:
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: Never
EOF

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/v1alpha1
    kind: PostgreSQLDatabaseInstance
    metadata:
    namespace: test
    name: postgres-test
    spec:
    parameters:
    allocatedStorage: 5
    deletionPolicy: Delete
    engineVersion: "12.4"
    finalDBSnapshotIdentifier: postgres-test-final-snapshot
    writeConnectionSecretToRef:
    name: postgres-test
    EOF
  2. Check the status of the PostgreSQL instance:

    kubectl -n test get PostgreSQLDatabaseInstance postgres-test
    NAME READY CONNECTION-SECRET AGE
    postgres-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/v1
kind: Job
metadata:
namespace: test
name: postgres-connection-test
spec:
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/v1alpha1
    kind: MySQLDatabaseInstance
    metadata:
    namespace: test
    name: mysql-test
    spec:
    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-test
    NAME READY CONNECTION-SECRET AGE
    postgres-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/v1
kind: Job
metadata:
namespace: test
name: database-connection-test
spec:
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_NAME
    NAME VERSION CLUSTER STATUS AGE
    CLUSTER_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 AGE
    CLUSTER_NAME-crossplane crossplane crossplane-1.0.0 Success 21h
    CLUSTER_NAME-crossplane-aws-rds crossplane-aws-rds crossplane-aws-rds Success 21h
    CLUSTER_NAME-crossplane-aws-s3 crossplane-aws-s3 crossplane-aws-s3 Success 21h
    CLUSTER_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