Compass

Overview

NOTE: Compass is a new, experimental component in Kyma. To learn how to enable it, read the installation document.

Compass is a central, multi-tenant system that allows you to connect Applications and manage them across multiple Kyma Runtimes. Using Compass, you can control and monitor your Application landscape in one central place. As an integral part of Kyma, Compass uses a set of features that Kyma provides, such as Istio, Prometheus, Monitoring, and Tracing. It also includes Compass UI Cockpit that exposes Compass APIs to users. Compass allows you to:

  • Connect and manage Applications and Kyma Runtimes in one central place
  • Store Applications and Runtimes configurations
  • Group Applications and Runtimes to enable integration
  • Communicate the configuration changes to Applications and Runtimes
  • Establish a trusted connection between Applications and Runtimes using various authentication methods

Compass by design does not participate in direct communication between Applications and Runtimes. It only sets up the connection. In case the cluster with Compass is down, the Applications and Runtimes cooperation still works.

Architecture

Components

Components

Application

Application represents any external system that you want to register to Compass with its API and Event definitions. These are the types of possible integration levels between an Application and Compass:

  • Manual integration - the Administrator manually provides API or Events metadata to Compass. Use this type of integration for simple use-case scenarios as it does not support all features.
  • Built-in integration - integration with Compass is built in the Application.
  • Proxy - a highly Application-specific proxy component provides the integration.
  • Integration System - a central service provides integration for the dedicated group of Applications across multiple tenants. It manages multiple instances of the given Application type. You can integrate multiple Integration Systems to support different types of Applications.

Kyma Runtime

Runtime is a system to which you can apply configuration provided by Compass. Your Runtime must get a trusted connection to Compass. It must also allow for fetching Application definitions and using these Applications in one-tenant scope. By default, Compass is integrated with Kyma (Kubernetes), but its usage can also be extended to other platforms, such as CloudFoundry or Serverless.

Runtime Agent

Runtime Agent is an integral part of every Runtime and it fetches the latest configuration from Compass. In the future releases, Runtime Agent will:

  • Provide Runtime specific information that will be displayed in the Compass UI, such as Runtime UI URL
  • Provide Compass with Runtime configuration, such as Event Gateway URL, that should be passed to an Application
  • Send Runtime health checks to Compass

Cockpit

Cockpit is a UI that calls Compass APIs. This component is interchangeable.

Gateway

Gateway proxies the tenant's incoming requests to the Director component. All communication, whether it comes from an Application or other external components, flows through Gateway.

Connector

Connector establishes trust between Applications and Runtimes. Currently, only client certificates are supported.

Director

Director handles the process of managing Applications and Runtimes. It also requests Application webhook APIs for credentials and exposes health information about Runtimes. This component has access to the storage.

Runtime Provisioner

Runtime Provisioner handles the creation, modification, and deletion of Runtimes. This component is interchangeable.

Basic architecture

The diagram presents the basic workflow between Applications, Runtimes, and Compass:

Basic architecture

  1. Administrator adds Runtimes and Applications, and configures them using Compass.
  2. Runtime Agent continuously fetches the latest configuration from Compass.
  3. If an Application has optional webhooks configured, Compass notifies an Application about any Events that concern the given Application.

Compass by design does not participate in direct communication between Applications and Runtimes. It only sets up the connection. After establishing a trusted connection between an Application and a Runtime, they communicate directly with each other.

Scenarios

In order to connect and group your Applications and Runtimes, assign them to the same scenario. A scenario is a simple label with the scenarios key. If an Application is not explicitly assigned to any scenario, it belongs to the default one. The Application is automatically removed from the default scenario after you assign it to any other scenario. By default, Runtimes are not assigned to any scenario. You can assign Applications and Runtimes to multiple scenarios. See the example:

Scenarios

Application 2 belongs to the campaign and marketing scenarios. Assuming that Application 2 only exposes APIs, you can assign both Runtime 1 and Runtime 2 to it. However, if Application 2 also exposes Events, you can assign it only to one Runtime. If you try to connect more Runtimes, Compass will not allow you to do so. Communication between components that do not belong to the same scenario, such as Application 3 and Runtime 1, is not possible.

Details

Runtime Provisioner

The Runtime Provisioner is a Compass component responsible for provisioning, installing, and deprovisioning clusters with Kyma (Kyma Runtimes). The relationship between clusters and Runtimes is 1:1.

It is powered by Hydroform and it allows you to provision the clusters in the following ways:

During the operation of provisioning, you can pass a list of Kyma components you want installed on the provisioned Runtime with their custom configuration, as well as a custom Runtime configuration.

Note that the operations of provisioning and deprovisioning are asynchronous. The operation of provisioning returns the Runtime Operation Status containing the Runtime ID and the operation ID. The operation of deprovisioning returns the operation ID. You can use the operation ID to check the Runtime Operation Status and the Runtime ID to check the Runtime Status.

The Runtime Provisioner exposes an API to manage cluster provisioning, installation, and deprovisioning.

Find the specification of the API here.

To access the Runtime Provisioner, forward the port that the GraphQL Server is listening on:

Click to copy
kubectl -n compass-system port-forward svc/compass-provisioner 3000:3000

When making a call to the Runtime Provisioner, make sure to attach a tenant header to the request.

Installation

Enable Compass in Kyma

To enable Compass in Kyma, follow the instructions for the custom component installation and enable the compass and compass-runtime-agent modules. You can also install Kyma on a cluster with the ready-to-use configurations for different modes. There are two modes in which you can enable Compass in Kyma: default Kyma installation and Compass as a Central Management Plane.

Default Kyma installation

This is a single-tenant mode which provides the complete cluster Kyma installation with all components, including Compass and Runtime Agent. In this mode, Runtime Agent is already connected to Compass and they both work in a single-tenant mode as well. Using this mode, you can register external Applications in Kyma. To enable it, follow the cluster Kyma installation and use the installer-cr-cluster-with-compass.yaml.tpl configuration file.

Kyma mode1

Compass as a Central Management Plane

This is a multi-cluster mode in which you need one cluster with Compass and at least one cluster with Kyma Runtime, which you can connect and manage using Compass. This mode allows you to integrate your Runtimes with Applications and manage them in one central place.

Kyma mode2

Kyma Compass

This is a multi-tenant and multi-Runtime mode that provides a cluster with Compass and only the selected Kyma components that Compass uses. To enable this mode, create this ConfigMap and then perform the cluster Kyma installation using the installer-cr-cluster-compass.yaml.tpl configuration file:

Click to copy
apiVersion: v1
kind: ConfigMap
metadata:
name: compass-overrides
namespace: kyma-installer
labels:
installer: overrides
component: compass
kyma-project.io/installation: ""
data:
# The parameter that enables the Compass gateway, as the default Kyma gateway is disabled in this installation mode
gateway.gateway.enabled: "true"
# The name of the currently used gateway
global.istio.gateway.name: compass-istio-gateway
# The Namespace of the currently used gateway
global.istio.gateway.namespace: compass-system
# The parameter that disables preconfiguration for the Compass Runtime Agent
global.agentPreconfiguration: "false"
# The Namespace with a Secret that contains a certificate for the Connector Service
global.connector.secrets.ca.namespace: compass-system

Kyma Runtime

This is a single-tenant mode that provides complete cluster Kyma installation with Runtime Agent. To enable this mode, follow the cluster Kyma installation and use the installer-cr-cluster-runtime.yaml.tpl configuration file.

Configuration

Runtime Provisioner chart

To configure the Runtime Provisioner chart, override the default values of its values.yaml file. This document describes the parameters that you can configure.

TIP: To learn more about how to use overrides in Kyma, see Helm overrides for Kyma installation.

Configurable parameters

This table lists the configurable parameters, their descriptions, and default values:

ParameterDescriptionDefault value
database.schemaFilePathFilepath for the database schemaassets/database/provisioner.sql
installation.timeoutKyma installation timeout30m
installation.errorsCountFailureThresholdNumber of installation errors that causes installation to fail5

Tutorials

Manage your Applications using Kyma Console and Compass UIs

This tutorial presents the basic flow in which you manually register an external Application's API into Compass and expose it into the Kyma Runtime. In the Kyma Runtime, you then create a lambda that calls the Application's API. While going through this tutorial, you will navigate between two UI views:

  • Compass UI, where you create connections between Applications, Runtimes, and scenarios
  • Kyma Console UI, where you manage resources used in your Application, such as services, lambdas, and bindings

Prerequisites

For simplicity reasons, use the available Order Service as the sample external Application for this tutorial. Prepare the following:

NOTE: Read this document to learn how to install Kyma with the Compass module.

Steps

Deploy the external Application

  1. Log in to the Kyma Console and create a new Namespace by selecting the Add new namespace button.

  2. In the Overview tab in your Namespace, select the Deploy new resource button and use the order-service file to connect the Application.

  3. In the APIs tab, copy the URL to your Application. You will use it in the Compass UI in the next steps.

Register your Application in the Compass UI

  1. Select Back to Namespaces in the top-left corner of the page, and go to the Compass tab in the left navigation panel. It will navigate you to the Compass UI. Select a tenant you want to work on from the drop-down list on the top navigation panel. For the purpose of this tutorial, select the default tenant. In the Runtimes tab, there is already the default kymaruntime that you can work on to complete this tutorial. Make sure that your Runtime is assigned to the DEFAULT scenario.

  2. Navigate to the Application tab in the main Console view and click Create Application to register your Application in Compass. For the purpose of this tutorial, name your Application test-app. By default, your Application is assigned to the DEFAULT scenario.

  3. Select test-app in the Applications view and add the API spec of the Order Service:

    a. Click the + button in the API Definitions section and fill in all the required fields.

    b. Paste the URL to your Application in the Target URL field.

    c. Click the Add specification button and upload the order-service API spec file.

    d. In the Credentials tab, choose None from the drop-down list to select the credentials type. For the purpose of this tutorial, there is no need to secure the connection. Click Create.

Use your Application in the Kyma Console UI

  1. Go back to the Kyma Console UI. You can see that the test-app Application is registered in the Applications view. Select test-app and bind it to your Namespace by selecting the Create Binding button.

  2. Select your Namespace from the drop-down list and go to the Catalog view. You will see your services available under the Services tab. Provision the service instance by choosing your service and clicking the Add once button in the top-right corner of the page.

  3. Create a lambda function. In the Overview tab, click the Deploy new resource button and upload the lambda.yaml file.

  4. Expose your lambda:

    a. Go to the Lambdas tab in the left navigation panel and choose the call-order-service lambda.

    b. In the Settings & Code section, click the Select Function Trigger button and expose your lambda via HTTPS.

    c. Untick the Enable authentication field as there is no need to secure the connection for the purpose of this tutorial.

    d. Click Add.

    e. Scroll down to the end of your lambda view and bind your lambda to your instance by clicking the Create Service Binding button in the Service Binding section. Choose the ServiceInstance you want to bind your lambda to, and click Create Service Binding.

    f. Save the settings in the right top-right corner of the page.

    g. Click the Lambdas tab and wait until the lambda status is completed and marked as 1/1.

  5. Test your lambda. Navigate to your lambda, and go to the Testing tab. After you click the Send button, you can see the following output in the Response field:

    Click to copy
    {
    "status": 200,
    "data": []
    }

    You can test your lambda by performing the following actions in the Payload field:

    • {"action":"add"} - adds the new order
    • {"action":"list"} - lists all orders (this is the default command executed after you click the Send button)
    • {"action":"delete"} - deletes all the orders

Cleanup

Clean up your cluster after going through this tutorial. To do so, delete your resources in the following order:

  1. Go to the Lambdas tab, unfold the vertical option menu and delete your lambda.

  2. Go to the Services tab and delete order-service.

  3. Go to the Deployments tab and delete the order-service deployment.

  4. Go to the APIs tab and delete the order-service API.

  5. Go to the Instances tab, navigate to Services, and deprovision your instance by selecting the trash bin icon.

  6. Go to the Overview section and unbind test-app from your Namespace.

  7. Go back to the Namespaces view and delete your Namespace.

  8. In the Compass UI, remove test-app from the Applications view. If you go back to the Applications view in the Kyma Console UI, you can see that the test-app Application is removed. It can take a moment, so refresh the Console UI if the Application is still there.

Provision clusters through Gardener

This tutorial shows how to provision clusters with Kyma Runtimes on Google Cloud Platform (GCP), Microsoft Azure, and Amazon Web Services (AWS) using Gardener.

Prerequisites

  • GCP
  • Azure
  • AWS

NOTE: To access the Runtime Provisioner, forward the port on which the GraphQL Server is listening.

Steps

  • GCP
  • Azure
  • AWS

The operation of provisioning is asynchronous. The operation of provisioning returns the Runtime Operation Status containing the Runtime ID (provisionRuntime.runtimeID) and the operation ID (provisionRuntime.id). Use the Runtime ID to check the Runtime Status. Use the provisioning operation ID to check the Runtime Operation Status and verify that the provisioning was successful.

NOTE: To see how to provide the labels, see this document. To see an example of label usage, go here.

Check Runtime Operation Status

This tutorial shows how to check the Runtime operation status for the operations of Runtime provisioning and deprovisioning.

Steps

NOTE: To access the Runtime Provisioner, forward the port on which the GraphQL Server is listening.

Make a call to the Runtime Provisioner with a tenant header to verify that (de)provisioning succeeded. Pass the ID of the operation as id.

Click to copy
query {
runtimeOperationStatus(id: "e9c9ed2d-2a3c-4802-a9b9-16d599dafd25") {
operation
state
message
runtimeID
}
}

A successful call returns a response which includes the status of the (de)provisioning operation (state) and the id of the (de)provisioned Runtime (runtimeID):

Click to copy
{
"data": {
"runtimeOperationStatus": {
"operation": "{"Provision"|"Deprovision"}",
"state": "Succeeded",
"message": "Operation succeeded.",
"runtimeID": "309051b6-0bac-44c8-8bae-3fc59c12bb5c"
}
}
}

The Succeeded status means that the operation of provisioning or deprovisioning was successful and the cluster was created or deleted respectively.

If you get the InProgress status, it means that the (de)provisioning has not yet finished. In that case, wait a few moments and check the status again.

Check Runtime Status

This tutorial shows how to check the Runtime status.

Steps

Make a call to the Runtime Provisioner with a tenant header to check the Runtime status. Pass the Runtime ID as id.

Click to copy
query { runtimeStatus(id: "{RUNTIME_ID}") {
lastOperationStatus {
id operation state message runtimeID
}
runtimeConnectionStatus {
status errors {
message
}
}
runtimeConfiguration {
clusterConfig {
__typename ... on GCPConfig {
bootDiskSizeGB name numberOfNodes kubernetesVersion projectName machineType zone region }
... on GardenerConfig {
name workerCidr region diskType maxSurge nodeCount volumeSizeGB projectName machineType targetSecret
autoScalerMin autoScalerMax provider maxUnavailable kubernetesVersion }
}
kymaConfig {
version components {
component
namespace configuration {
key
value
secret
}
}
configuration {
key value secret
}
}
kubeconfig
}
}
}

An example response for a successful request looks like this:

Click to copy
{
"data": {
"runtimeStatus": {
"lastOperationStatus": {
"id": "20ed1cfb-7407-4ec5-89af-c550eb0fce49",
"operation": "Provision",
"state": "Succeeded",
"message": "Operation succeeded.",
"runtimeID": "b70accda-4008-466c-96ec-9b42c2cfd264"
},
"runtimeConnectionStatus": {
"status": "Pending",
"errors": null
},
"runtimeConfiguration": {
"clusterConfig": {CLUSTER_CONFIG},
"kymaConfig": {
"version": "1.8.0",
"components": [{COMPONENTS_LIST}]
},
"kubeconfig": {KUBECONFIG}
}
}
}
}

Deprovision clusters

This tutorial shows how to deprovision clusters with Kyma Runtimes.

Steps

NOTE: To access the Runtime Provisioner, forward the port on which the GraphQL Server is listening.

To deprovision a Runtime, make a call to the Runtime Provisioner with a tenant header using a mutation like this:

Click to copy
mutation { deprovisionRuntime(id: "61d1841b-ccb5-44ed-a9ec-45f70cd1b0d3") }

A successful call returns the ID of the deprovisioning operation:

Click to copy
{
"data": {
"deprovisionRuntime": "c7e6727f-16b5-4748-ac95-197d8f79d094"
}
}

The operation of deprovisioning is asynchronous. Use the deprovisioning operation ID (deprovisionRuntime) to check the Runtime Operation Status and verify that the deprovisioning was successful. Use the Runtime ID (id) to check the Runtime Status.

Establish a secure connection with Compass

To establish a secure connection with Compass and generate the client certificate, follow this tutorial.

Prerequisites

  • OpenSSL toolkit to create a Certificate Signing Request (CSR), keys, and certificates which meet high security standards
  • Compass (version 1.8 or higher)
  • Registered Application
  • Runtime connected to Compass

Steps

  1. Get the Connector URL and the one-time token.

    To get the Connector URL and the one-time token which allow you to fetch the required configuration details, use the Compass Console.

    Alternatively, make a call to the Director including the Tenant header with Tenant ID and authorization header with the Dex Bearer token. Use the following mutation:

    Click to copy
    mutation {
    result: generateOneTimeTokenForApplication(id: "{APPLICATION_ID}") {
    token
    connectorURL
    }
    }

    NOTE: The one-time token expires after 5 minutes.

  2. Get the CSR information and configuration details from Kyma using the one-time token.

    To get the CSR information and configuration details, send this GraphQL query to the Connector URL. You must include the connector-token header containing the one-time token when making the call.

    Click to copy
    query {
    result: configuration {
    token {
    token
    }
    certificateSigningRequestInfo {
    subject
    keyAlgorithm
    }
    managementPlaneInfo {
    directorURL
    certificateSecuredConnectorURL
    }
    }
    }

    A successful call returns the data requested in the query including a new one-time token.

  3. Generate a key and a Certificate Signing Request (CSR).

    Generate a CSR with the following command. SUBJECT is the certificate subject data returned with the CSR information as subject.

    Click to copy
    export KEY_LENGTH=4096
    openssl genrsa -out compass-app.key $KEY_LENGTH
    openssl req -new -sha256 -out compass-app.csr -key compass-app.key -subj "{SUBJECT}"

    NOTE: The key length is configurable, however, 4096 is the recommended value.

  4. Sign the CSR and get a client certificate.

    Encode the obtained CSR with base64:

    Click to copy
    openssl base64 -in compass-app.csr

    To get the CSR signed, use the encoded CSR in this GraphQL mutation:

    Click to copy
    mutation {
    result: signCertificateSigningRequest(csr: "{BASE64_ENCODED_CSR}") {
    certificateChain
    caCertificate
    clientCertificate
    }
    }

    Send the modified GraphQL mutation to the Connector URL. You must include the connector-token header containing the one-time token fetched with the configuration.

    The response contains a certificate chain, a valid client certificate signed by the Kyma Certificate Authority (CA), and the CA certificate.

  5. Decode the certificate chain.

    After you receive the certificates, decode the certificate chain with the base64 method and use it in your application:

    Click to copy
    base64 -d {CERTIFICATE_CHAIN}

    NOTE: To learn how to renew a client certificate, read this tutorial.

Maintain a secure connection with Compass

After you have established a secure connection with Compass, you can fetch the configuration details and renew the client certificate before it expires. To renew the client certificate, follow the steps in this tutorial.

Prerequisites

Steps

  1. Get the CSR information with the configuration details.

    To fetch the configuration, make a call to the Certificate-Secured Connector URL using the client certificate. The Certificate-Secured Connector URL is the certificateSecuredConnectorURL obtained when establishing a secure connection with Compass. Send this query with the call:

    Click to copy
    query {
    result: configuration {
    certificateSigningRequestInfo {
    subject
    keyAlgorithm
    }
    managementPlaneInfo {
    directorURL
    }
    }
    }

    A successful call returns the requested configuration details.

  2. Generate a key and a Certificate Signing Request (CSR).

    Generate a CSR with this command using the certificate subject data obtained with the CSR information:

    Click to copy
    export KEY_LENGTH=4096
    openssl genrsa -out compass-app.key $KEY_LENGTH
    openssl req -new -sha256 -out compass-app.csr -key compass-app.key -subj "{SUBJECT}"

    NOTE: The key length is configurable, however, 4096 is the recommended value.

  3. Sign the CSR and renew the client certificate.

    Encode the obtained CSR with base64:

    Click to copy
    openssl base64 -in compass-app.csr

    Send the following GraphQL mutation with the encoded CSR to the Certificate-Secured Connector URL:

    Click to copy
    mutation {
    result: signCertificateSigningRequest(csr: "{BASE64_ENCODED_CSR}") {
    certificateChain
    caCertificate
    clientCertificate
    }
    }

    The response contains a renewed client certificate signed by the Kyma Certificate Authority (CA), certificate chain, and the CA certificate.

  4. Decode the certificate chain.

    The returned certificates and the certificate chain are base64-encoded and need to be decoded before use. To decode the certificate chain, run:

    Click to copy
    base64 -d {CERTIFICATE_CHAIN}

NOTE: To learn how to revoke a client certificate, read this tutorial.

Revoke a client certificate

After you have established a secure connection with Compass and generated a client certificate, you may want to revoke this certificate at some point. To revoke a client certificate, follow the steps in this tutorial.

NOTE: A revoked client certificate remains valid until it expires, but it cannot be renewed.

Prerequisites

NOTE: To see how to maintain a secure connection with Compass and renew a client certificate, read this tutorial.

Steps

  1. Revoke the client certificate

    To revoke a client certificate, make a call to the Certificate-Secured Connector URL using the client certificate. The Certificate-Secured Connector URL is the certificateSecuredConnectorURL obtained when establishing a secure connection with Compass. Send this mutation with the call:

    Click to copy
    mutation { result: revokeCertificate }

    A successful call returns the following response:

    Click to copy
    {"data":{"result":true}}