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 fetches the certificate from the Connector to initialize connection with Compass.
Runtime Agent stores the certificate and key for the Connector and the Director in the Secret.
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.
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.
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:
Parameter | Description | Example value |
---|---|---|
CONNECTOR_URL | Connector URL | https://compass-gateway.kyma.local/connector/graphql |
RUNTIME_ID | ID of the Runtime registered in the Director | 1ae04041-17e5-478f-91f8-3a2ddc7700de |
TENANT | Tenant ID | 3e64ebae-38b5-46a0-b1ed-9ccee153a0ae |
TOKEN | One-time token generated for the Runtime | 2I7VVX5CqxHioEBQGPxWSp3k90uw51tmx5dbo0IZd5VNFzGoPfppYrMIuoCNwFOKp05wsioJNLJYxdI-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:
cat <<EOF | kubectl apply -f -apiVersion: v1kind: ConfigMapmetadata: 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:
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.
apiVersion: compass.kyma-project.io/v1alpha1kind: CompassConnectionmetadata: name: compass-connectionspec: 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/graphqlstatus: 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:
Parameter | Required | Description |
---|---|---|
metadata.name | Yes | Specifies the name of the CR. |
spec.managementInfo.connectorUrl | Yes | Connector URL used for maintaining secure connection. |
spec.managementInfo.directorUrl | Yes | Director URL used for fetching Applications. |
These components use this CR:
Component | Description |
---|---|
Runtime Agent | Stores 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.
Field | Description |
---|---|
status.connectionStatus | Describes the status of the connection with Compass. |
status.connectionStatus.certificateStatus | Provides the dates of when the certificate was issued and when it expires. |
status.connectionStatus.established | Provides the date of when the connection was established. |
status.connectionStatus.lastSuccess | Provides the date of the last successful synchronization with the Connector. |
status.connectionStatus.lastSync | Provides the date of the last synchronization attempt. |
status.connectionStatus.renewed | Provides the date of the last certificate renewal. |
status.synchronizationStatus | Describes the status of the synchronization with the Director. |
status.synchronizationStatus.lastAttempt | Provides the date of the last synchronization attempt with the Director. |
status.synchronizationStatus.lastSuccessfulFetch | Provides the date of the last successful fetch of resources from the Director. |
status.synchronizationStatus.lastSuccessfulApplication | Provides 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
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 andauthorization
header with the Dex Bearer token. Use the following mutation:Click to copymutation {result: requestOneTimeTokenForApplication(id: "{APPLICATION_ID}") {tokenconnectorURL}}NOTE: The one-time token expires after 5 minutes.
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 copyquery {result: configuration {token {token}certificateSigningRequestInfo {subjectkeyAlgorithm}managementPlaneInfo {directorURLcertificateSecuredConnectorURL}}}A successful call returns the data requested in the query including a new one-time token.
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 assubject
.Click to copyexport KEY_LENGTH=4096openssl genrsa -out compass-app.key $KEY_LENGTHopenssl 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.
Sign the CSR and get a client certificate.
Encode the obtained CSR with base64:
Click to copyopenssl base64 -in compass-app.csrTo get the CSR signed, use the encoded CSR in this GraphQL mutation:
Click to copymutation {result: signCertificateSigningRequest(csr: "{BASE64_ENCODED_CSR}") {certificateChaincaCertificateclientCertificate}}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.
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 copybase64 -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
- 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
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 copyquery {result: configuration {certificateSigningRequestInfo {subjectkeyAlgorithm}managementPlaneInfo {directorURL}}}A successful call returns the requested configuration details.
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 copyexport KEY_LENGTH=4096openssl genrsa -out compass-app.key $KEY_LENGTHopenssl 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.
Sign the CSR and renew the client certificate.
Encode the obtained CSR with base64:
Click to copyopenssl base64 -in compass-app.csrSend the following GraphQL mutation with the encoded CSR to the Certificate-Secured Connector URL:
Click to copymutation {result: signCertificateSigningRequest(csr: "{BASE64_ENCODED_CSR}") {certificateChaincaCertificateclientCertificate}}The response contains a renewed client certificate signed by the Kyma Certificate Authority (CA), certificate chain, and the CA certificate.
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 copybase64 -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
- 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
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 copymutation { 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:
cat <<EOF | kubectl -n compass-system apply -f -apiVersion: v1data: CONNECTOR_URL: $({CONNECTOR_URL}) RUNTIME_ID: $({RUNTIME_ID}) TENANT: $({TENANT_ID}) TOKEN: $({ONE_TIME_TOKEN})kind: Secretmetadata: name: compass-agent-configuration namespace: compass-systemEOF
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:
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.