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. It also provides Runtime specific information that is displayed in the Compass UI, such as Runtime UI URL, and it provides Compass with Runtime configuration, such as Event Gateway URL, that should be passed to an Application. In the future releases, Runtime Agent will 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.

Detailed workflow

The basic flow of interactions between an Application, Runtime, and Compass is as follows:

  1. Connecting Application
  2. Registering Runtime
  3. Changing configuration

Connecting Application

Connecting an Application consists of two phases: Application pairing and API registration. In the process of connecting a new Application, two Compass components are involved: the Director and the Connector.

Application pairing phase

Application pairing phase is a process of creating a new Application and establishing a trusted connection between the Application and Compass. The workflow looks as follows:

  1. Administrator sends a request to register a new Application in Compass.
  2. Director registers the Application.
  3. Director sends back Application details, along with its unique ID.
  4. Administrator requests Application pairing with the Connector.
  5. Connector generates a one-time token and sends it back to the Administrator.
  6. Administrator passes the one-time token to the Application.
  7. Application uses this token to establish a trusted connection with Compass.

API registration phase

API registration phase is a process of registering new API and Event Definitions, which consists of two steps:

  1. Application sends a request to the Director to register an API or Event Definition.
  2. Director returns the operation result to the Application.

Registering Runtime

The process of registering a new Runtime looks as follows:

  1. Administrator sends a request to provision a new Runtime.
  2. Runtime Provisioner requests Runtime configuration from the Director.
  3. Director returns Runtime configuration to the Runtime Provisioner.
  4. Runtime Provisioner requests a one-time token from the Connector.
  5. Connector generates a one-time token for the Runtime.
  6. Connector returns the token to the Runtime Provisioner.
  7. Runtime Provisioner provisions the Runtime.
  8. Runtime Provisioner injects Runtime configuration along with the one-time token to the Runtime Agent.
  9. Runtime Agent uses the token to set up a trusted connection between Compass and the Runtime.

When the Runtime is ready, Runtime Agent notifies the Director about the Runtime status. When the Director receives a notification that a Runtime is ready, it passes the notification to every Application in a group assigned to this Runtime using Application Webhook API.

Changing configuration

The following section describes how configuration updates work for Applications and Runtimes.

Application configuration update

There are two options for updating Application configuration:

  • Periodically fetching Application configuration
  • Exposing Application Webhook API to get notifications on configuration updates

In the first case, the Application periodically pulls configuration details, such as eventURL, for connected Runtimes.

In the second case, if configuration for any connected Runtime changes, Application Webhook API notifies an Application that new configuration details are available. The following diagram shows the interaction between the Runtime Agent, the Director, and an Application when a new Runtime is configured successfully:

  1. Runtime Agent sends a request to change Application configuration.
  2. Director notifies the Application about the request.
  3. Application changes configuration for the Runtime.
  4. Runtime Agent gets a new configuration from the Director.

Runtime configuration update

Runtime Agent gets Runtime configuration details from the Director and applies the configuration asynchronously. The configuration details include information such as the list of Applications and their credentials. Runtime Agent periodically checks for new configuration details and applies the changes.

Runtime Agent architecture

This document presents the workflow of Runtime Agent.

Runtime Agent architecture

  1. Runtime Agent fetches the certificate from the Connector to initialize connection with Compass.

  2. Runtime Agent stores the certificate and key for the Connector and the Director in the Secret.

  3. Runtime Agent synchronizes the Runtime with the Director. It does so by:

  • fetching new Applications from the Director and creating them in the Runtime
  • removing from the Runtime the Applications that no longer exist in the Director.
  1. Runtime Agent labels the Runtime data in the Director with the Event Gateway URL and the Console URL of the Kyma cluster. These URLs are displayed in the Compass UI.

  2. Runtime Agent renews the certificate for the Connector and the Director to maintain connection with Compass. This only happens if the remaining validity period for the certificate passes a certain threshold.

Details

Labels

A label is a key-value pair that you can add to every top-level entity, such as an Application or a Runtime. Labels allow you to enrich Applications and Runtimes with additional information.

Use GraphQL mutations to set labels on your Applications and Runtimes. For example, to set the test:val label on your Application, use:

Click to copy
mutation {
result: setApplicationLabel(
applicationID: "{YOUR_APPLICATION_ID}"
key: "test"
value: "val"
) {
key
value
}
}

LabelDefinitions

For every label, you can create a related LabelDefinition to set validation rules for values using a JSON schema. It allows you to search for all Applications and Runtimes label keys used in a given tenant. LabelDefinitions are optional, but they are created automatically if the user adds labels for which LabelDefinitions do not exist. You can manage LabelDefinitions using the following mutations and queries:

Click to copy
type Query {
labelDefinitions: [LabelDefinition!]!
labelDefinition(key: String!): LabelDefinition
}
type Mutation {
createLabelDefinition(in: LabelDefinitionInput!): LabelDefinition!
updateLabelDefinition(in: LabelDefinitionInput!): LabelDefinition!
deleteLabelDefinition(key: String!, deleteRelatedLabels: Boolean=false): LabelDefinition!
}

TIP: For all the GraphQL query and mutation examples that you can use, go to this directory.

LabelDefinition key has to be unique for a given tenant. You can provide only one value for a given label. However, this label can contain many elements, depending on the LabelDefinition schema. In the following example, the type of the label value is Any, which means that the value can be of any type, such as JSON, string, int etc.:

Click to copy
setApplicationLabel(applicationID: ID!, key: String!, value: Any!): Label!

Define and set LabelDefinitions

See the example of how you can create and set a LabelDefinition:

Click to copy
createLabelDefinition(in: {
key:"supportedLanguages",
schema:"{
"type": "array",
"items": {
"type": "string",
"enum": ["Go", "Java", "C#"]
}
}"
}) {...}
setApplicationLabel(applicationID: "123", key: "supportedLanguages", value:["Go"]) {...}

Edit LabelDefinitions

You can edit LabelDefinitions using a mutation. When editing a LabelDefinition, make sure that all labels are compatible with the new definition. Otherwise, the mutation is rejected with a clear message that there are Applications or Runtimes that have an invalid label according to the new LabelDefinition. In such a case, you must either:

  • Remove incompatible labels from specific Applications and Runtimes, or
  • Remove the old LabelDefinition from all labels using cascading deletion.

For example, let's assume we have the following LabelDefinition:

Click to copy
key:"supportedLanguages",
schema:{
"type": "array",
"items": {
"type": "string",
"enum": ["Go", "Java", "C#"]
}
}

If you want to add a new language to the list, provide such a mutation:

Click to copy
updateLabelDefinition(in: {
key:"supportedLanguages",
schema:{
"type": "array",
"items": {
"type": "string",
"enum": ["Go", "Java", "C#","ABAP"]
}
}
}) {...}

Remove LabelDefinitions

Use this mutation to remove a LabelDefinition:

Click to copy
deleteLabelDefinition(key: String!, deleteRelatedLabels: Boolean=false): LabelDefinition

This mutation allows you to remove only definitions that are not used. If you want to delete a LabelDefinition with all its values, set the deleteRelatedLabels parameter to true.

LabelFilters

You can define a LabelFilter to list the top-level entities according to their labels. You can search for Applications and Runtimes by label keys or by label keys and their values. To search for a given Application or Runtime, use this query:

Click to copy
applications(filter: [LabelFilter!], first: Int = 100, after: PageCursor): ApplicationPage!

To search for all objects with a given label ignoring their values, use:

Click to copy
query {
applications(filter:[{key:"scenarios"
}]) {
data {
name
labels
}
totalCount
}
}

To filter objects by their key and string value, use this query:

Click to copy
runtimes(filter: { key: "{KEY}" query: "\"{VALUE}\"" })

You can also search for objects by their key and array values. In the query field, use only the limited SQL/JSON path expressions. The supported syntax is $[*] ? (@ == "{VALUE}" ). For example, to filter all objects assigned to the default scenario, run:

Click to copy
query {
applications(filter:[{key:"scenarios",
query:"$[*] ? (@ == \"DEFAULT\")"}]) {
data {
name
labels
}
totalCount
}
}

Scenarios label

Every Application is labeled with the special Scenarios label which automatically has the default value assigned. As every Application has to be assigned to at least one scenario, if no scenarios are explicitly specified, the default scenario is used.

When you create a new tenant, the Scenarios LabelDefinition is created. It defines a list of possible values that can be used for the Scenarios label. Every time you create or modify an Application, there is a step that ensures that Scenarios label exists. You can add or remove values from the Scenarios LabelDefinition list, but neither the default value, nor the Scenarios label can be removed.

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 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.

Runtime Agent

Runtime Agent is a Kyma component that connects to Compass.

The main responsibilities of the component are:

  • Establishing a trusted connection between the Kyma Runtime and Compass
  • Renewing a trusted connection between the Kyma Runtime and Compass
  • Synchronizing with the Director by fetching new Applications from the Director and creating them in the Runtime, and removing from the Runtime Applications that no longer exist in the Director.

Initializing connection

Runtime Agent connects to Compass using a one-time token from the Connector and exchanges it for a certificate, which is later used to fetch Applications from the Director.

The initial connection requires the following parameters:

ParameterDescriptionExample value
CONNECTOR_URLConnector URLhttps://compass-gateway.kyma.local/connector/graphql
RUNTIME_IDID of the Runtime registered in the Director1ae04041-17e5-478f-91f8-3a2ddc7700de
TENANTTenant ID-
TOKENOne-time token generated for the Runtime-

Runtime Agent reads this configuration from the ConfigMap specified in the Runtime Agent Deployment (compass-agent-configuration by default).

To see how to create the ConfigMap, see this tutorial.

Connection status

The connection status is preserved in the CompassConnection Custom Resource (CR). This CR also stores the Connector URL and the Director URL.

Reconnecting Runtime Agent

If the connection with Compass fails, Runtime Agent keeps trying to connect with the token from the ConfigMap. If the connection is established successfully, Runtime Agent ignores the ConfigMap until the connection is lost.

To force Runtime Agent to reconnect using the parameters from the ConfigMap, delete the Compass Connection CR:

Click to copy
kubectl delete compassconnection compass-connection

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

Kyma mode1

This is a single-tenant mode which provides the complete cluster Kyma installation with all components, including Compass and the Runtime Agent. In this mode, the 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 using the installer-cr-cluster-with-compass.yaml.tpl configuration file. Before you start the installation, apply the following ConfigMap which enables the API Packages functionality:

Click to copy
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
name: api-packages-override
namespace: kyma-installer
labels:
installer: overrides
kyma-project.io/installation: ""
data:
global.enableAPIPackages: "true"
EOF

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 the Runtime Agent. To enable this mode, follow the cluster Kyma installation using the installer-cr-cluster-runtime.yaml.tpl configuration file. Before you start the installation, apply the following ConfigMap which enables the API Packages functionality:

Click to copy
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
name: api-packages-override
namespace: kyma-installer
labels:
installer: overrides
kyma-project.io/installation: ""
data:
global.enableAPIPackages: "true"
EOF

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
gardener.projectName of the Gardener project connected to the service account
gardener.kubeconfigBase64-encoded Gardener service account key
provisionerProvisioning mechanism used by the Runtime Provisioner (Gardener or Hydroform)gardener
installation.timeoutKyma installation timeout30m
installation.errorsCountFailureThresholdNumber of installation errors that causes installation to fail5

Custom Resource

CompassConnection

The compassconnections.compass.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to preserve the status of the connection between Runtime Agent and Compass. The CompassConnection custom resource (CR) contains the connection statuses and Compass URLs. To get the up-to-date CRD and show the output in the yaml format, run this command:

Click to copy
kubectl get crd compassconnections.compass.kyma-project.io -o yaml

Sample custom resource

This is a sample resource that registers the compass-agent-connection CompassConnection which preserves the status of the connection between Runtime Agent and Compass. It also stores the URLs for the Connector and the Director.

Click to copy
apiVersion: compass.kyma-project.io/v1alpha1
kind: CompassConnection
metadata:
name: compass-connection
spec:
managementInfo:
connectorUrl: https://compass-gateway-mtls.34.76.33.244.xip.io/connector/graphql
directorUrl: https://compass-gateway-mtls.34.76.33.244.xip.io/director/graphql
status:
connectionState: ConnectionMaintenanceFailed
connectionStatus:
certificateStatus:
acquired: "2020-02-11T10:35:22Z"
notAfter: "2020-05-11T10:35:22Z"
notBefore: "2020-02-11T10:35:22Z"
established: "2020-02-11T10:35:22Z"
lastSuccess: "2020-02-12T10:45:10Z"
lastSync: "2020-02-12T12:37:48Z"
renewed: null
synchronizationStatus:
lastAttempt: "2020-02-12T10:45:10Z"
lastSuccessfulApplication: "2020-02-12T10:45:10Z"
lastSuccessfulFetch: "2020-02-12T10:45:10Z"

Custom resource parameters

This table lists all the possible parameters of the CompassConnection custom resource together with their descriptions:

ParameterRequiredDescription
metadata.nameYesSpecifies the name of the CR.
spec.managementInfo.connectorUrlYesConnector URL used for maintaining secure connection.
spec.managementInfo.directorUrlYesDirector URL used for fetching Applications.

These components use this CR:

ComponentDescription
Runtime AgentStores the Connector and Director URLs and preserves the status of the connection with Compass in this CR.

Additional information

Runtime Agent adds the status section which describes the statuses of the connection and synchronization to the created CR periodically. This table lists the fields of the status section.

FieldDescription
status.connectionStatusDescribes the status of the connection with Compass.
status.connectionStatus.certificateStatusProvides the dates of when the certificate was issued and when it expires.
status.connectionStatus.establishedProvides the date of when the connection was established.
status.connectionStatus.lastSuccessProvides the date of the last successful synchronization with the Connector.
status.connectionStatus.lastSyncProvides the date of the last synchronization attempt.
status.connectionStatus.renewedProvides the date of the last certificate renewal.
status.synchronizationStatusDescribes the status of the synchronization with the Director.
status.synchronizationStatus.lastAttemptProvides the date of the last synchronization attempt with the Director.
status.synchronizationStatus.lastSuccessfulFetchProvides the date of the last successful fetch of resources from the Director.
status.synchronizationStatus.lastSuccessfulApplicationProvides the date of the last successful application of resources fetched from Compass.

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:

  • order-service file that contains the service definition, deployment, and its API
  • API specification of order-service
  • Lambda function that calls order-service for orders
  • Kyma cluster with the Compass module and the API Packages feature enabled

NOTE: Read this document to learn how to install Kyma with the Compass module and the API Packages feature.

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. Open a separate tab in your browser and go to https://compass.{CLUSTER_DOMAIN}. It will navigate you to the Compass UI. From the drop-down list on the top navigation panel, select a tenant you want to work on. 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. In the left navigation panel, navigate to the Application tab and click Create application... to register your Application in Compass. Choose From scratch from the drop-down list. 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 Packages section and fill in all the required fields. For the purpose of this tutorial, name your Package test-package.

    b. 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.

    c. Navigate to the test-package Package and click the + button in the API Definitions section. Fill in all the required fields. In the Target URL field, paste the URL to your Application.

    d. Click the Add specification button and upload the order-service API spec file. 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. From the drop-down list in the top-right corner, select your Namespace and go to the Catalog view. You will see your services available under the Services tab. Provision the service instance by choosing your Package and clicking the Add 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 file with the lambda function.

  4. Expose your lambda:

    a. In the left navigation panel, go to the Lambdas tab and click 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. Click Add.

    d. 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.

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

    f. 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.

    NOTE: To access the Compass Console, go to the https://compass.{CLUSTER_DOMAIN} URL and enter your Kyma credentials.

    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}}

Configure Runtime Agent with Compass

This tutorial shows how to configure Runtime Agent with Compass.

Prerequisites

  • Compass (version matching Runtime Agent)
  • Runtime connected to Compass and the Runtime ID
  • Connector URL
  • One-time token from the Connector
  • Tenant ID

Steps

To configure Runtime Agent with Compass, you need to create a ConfigMap in the Runtime Agent Deployment. The default deployment is compass-agent-configuration. To create the ConfigMap, run:

Click to copy
cat <<EOF | kubectl -n compass-system apply -f -
apiVersion: v1
data:
CONNECTOR_URL: {CONNECTOR_URL}
RUNTIME_ID: {RUNTIME_ID}
TENANT: {TENANT_ID}
TOKEN: {ONE_TIME_TOKEN}
kind: ConfigMap
metadata:
name: compass-agent-configuration
namespace: compass-system
EOF