Runtime Agent is a Kyma component that connects to Compass. It is an integral part of every Kyma 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. To learn more, read the section on configuring the Runtime.

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.

NOTE: Go to the Compass repository to learn how to install Compass. However, bear in mind that the Compass component and its integration with Kyma are both experimental.

This document presents the workflow of the Runtime Agent.

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.

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

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

NOTE: To represent API and Event Definitions of the Applications connected to a Runtime, Open Service Broker API usage is recommended.

In a Kyma Runtime, during Runtime configuration, Application's Packages are integrated into Service Catalog using Application custom resources and Application Broker. By default, a single Application is represented as a ServiceClass, and a single Package is represented as a ServicePlan in Service Catalog. Refer to the documentation to learn more about API Packages.

Runtime Agent periodically requests for the configuration of its Runtime from Compass. Changes in the configuration for the Runtime are applied by the Runtime Agent on the Runtime.

To fetch the Runtime configuration, Runtime Agent calls the applicationsForRuntime query offered by the Compass component called Director. The response for the query contains Applications assigned for the Runtime. Each Application contains only credentials that are valid for the Runtime that called the query. Each Runtime Agent can fetch the configurations for Runtimes that belong to its tenant.

Runtime Agent reports back to the Director the Runtime-specific LabelDefinitions, which represent Runtime configuration, together with their values. Runtime-specific LabelDefinitions are Events Gateway URL and Runtime Console URL.

To enable Kyma with the Runtime Agent, follow the cluster Kyma installation using the installer-cr-cluster-runtime.yaml.tpl configuration file and enable the compass-runtime-agent module. The default legacy mode used in Kyma does not support integration with Compass. For that reason, before you start the installation, apply the following ConfigMap which disables components used in the legacy mode, such as the Application Registry and the Connector Service:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: disable-legacy-connectivity-override
  namespace: kyma-installer
  labels:
    installer: overrides
    kyma-project.io/installation: ""
data:
  global.disableLegacyConnectivity: "true"
EOF

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

• OpenSSL toolkit to create a Certificate Signing Request (CSR), keys, and certificates which meet high security standards
• Compass
• Registered Application
• Runtime connected to Compass
• Established secure connection with Compass

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

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

• OpenSSL toolkit to create a Certificate Signing Request (CSR), keys, and certificates which meet high security standards
• Compass
• Registered Application
• Runtime connected to Compass
• Established secure connection with Compass

NOTE: To see how to maintain a secure connection with Compass and renew a client certificate, read the 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}}

This tutorial shows how to configure the Runtime Agent with Compass.

Prerequisites

• Compass
• Runtime connected to Compass and the Runtime ID
• Connector URL
• One-time token from the Connector
• Tenant ID

NOTE: Learn also about the parameters required to initialize the connection between the Runtime Agent and Compass.

Steps

To configure the Runtime Agent with Compass, you need to create a Secret in the Runtime Agent Namespace and specify it in the Runtime Agent Deployment. The default Secret is compass-agent-configuration. To create the Secret, run:

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: Secret
metadata:
  name: compass-agent-configuration
  namespace: compass-system
EOF

This tutorial shows how to reconnect the Runtime Agent with Compass after the established connection was lost.

Prerequisites

• Compass
• ConfigMap created

Steps

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

kubectl delete compassconnection compass-connection

After the Connection CR is removed, the Runtime Agent will try to connect to Compass using the token from the Secret.