Runtime Agent

Overview

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.

Architecture

This document presents the workflow of the 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

Connection with Compass

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 ID3e64ebae-38b5-46a0-b1ed-9ccee153a0ae
TOKENOne-time token generated for the Runtime2I7VVX5CqxHioEBQGPxWSp3k90uw51tmx5dbo0IZd5VNFzGoPfppYrMIuoCNwFOKp05wsioJNLJYxdI-LKlUYA==

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

To see how to create the Secret, see the 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, the Runtime Agent keeps trying to connect with the token from the Secret. If the connection is established successfully, the Runtime Agent ignores the Secret until the connection is lost.

To see how to reconnect the Runtime Agent with Compass, see the tutorial.

Configuring the Runtime

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.

Installation

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:

Click to copy
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

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

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
  • 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: requestOneTimeTokenForApplication(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 the 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 the 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 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}}

Configure Runtime Agent with Compass

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:

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

Reconnect Runtime Agent with Compass

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

Prerequisites

Steps

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

Click to copy
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.