This generic Operator is capable of deploying any application image and can be imported into any runtime-specific Operator as library of application capabilities. This architecture ensures compatibility and consistency between all runtime Operators, allowing everyone to benefit from the functionality added in this project.
Your environment must meet cluster, sizing, persistent storage, and network requirements for Runtime Component operator.
If you are installing a Runtime Component operator on an Red Hat OpenShift cluster, your environment must meet Red Hat OpenShift Container Platform (OCP) cluster requirements.
Runtime Component operator requires an OCP version 4.16, OCP version 4.15, OCP version 4.14, or OCP version 4.12 cluster on Linux x86_64 (amd64), Linux on Power (ppc64le), or Linux on IBM Z (s390x) platform, with cluster-admin permissions. To manage OCP projects with OCP CLI (oc) commands, the installation also requires the OCP CLI.
By default, certificates are generated by using the OpenShift certificate manager. If you want to use the manageTLS
capability and use a different certificate manager (such as cert-manager) to generate and manage the certificates, you must install it.
If you are installing a Runtime Component operator on a Kubernetes cluster, your environment must meet the Kubernetes cluster requirements.
Runtime Component operator requires a Kubernetes version 1.29, 1.28, 1.27, 1.26, or 1.25 cluster on Linux x86_64 (amd64), Linux on Power (ppc64le), or Linux on IBM Z (s390x) platform, with cluster-admin permissions.
If you plan to use Operator Lifecycle Manager (OLM), it must be installed on your cluster.
If you want to use the manageTLS
capability, you must have a certificate manager (such as cert-manager) installed.
Before you can use the Ingress resource to expose your application, you must install an ingress controller such as Nginx or Traefik.
Your environment must meet sizing requirements for Runtime Component operator.
Project |
CPU request (cores) |
Memory request (Mi) |
Disk space (Gi) |
Notes |
Runtime Component operator |
0.2 (limit: 0.4) |
128 (limit: 1024) |
N/A |
Applications that are deployed and managed by the operator have their own resource requests and limits as specified in the Runtime Component operator custom resources. |
Note
|
The values in the tables do not include any requirements inherent in the storage provider. The storage infrastructure might require more resources (for example, CPU or memory) from the worker nodes. |
No storage requirements exist for Runtime Component operator.
You are responsible for configuring and managing storage for any applications that you deploy with Runtime Component operator.
Your environment must meet network requirements for Runtime Component operator.
Hostnames |
Ports and Protocols |
Purpose |
icr.io, cp.icr.io |
443 (HTTP over TLS) |
The listed domain is the container image registry that is used as part of the Runtime Component operator installation. This registry is also used when Runtime Component operator and dependency software levels are updated. |
Use the instructions for one of the releases to install the operator into a Kubernetes cluster.
The Runtime Component Operator is available for the following CPU architectures:
-
Linux® x86_64 (amd64)
-
Linux® on IBM® Z (s390x)
-
Linux® on Power® (ppc64le)
The Runtime Component Operator can be installed to:
-
watch own namespace
-
watch another namespace
-
watch all namespaces in the cluster
Appropriate cluster roles and bindings are required to watch another namespace, or to watch all namespaces.
Note
|
The Runtime Component Operator can only interact with resources it is given permission to interact through Role-based access control (RBAC). Some of the operator features described in this document require interacting with resources in other namespaces. In that case, the operator must be installed with correct ClusterRole definitions.
|
The architecture of the Runtime Component Operator follows the basic controller pattern: the Operator container with the controller is deployed into a Pod and listens for incoming resources with Kind: RuntimeComponent
. Creating a RuntimeComponent
custom resource (CR) triggers the Runtime Component Operator to create, update or delete Kubernetes resources needed by the application to run on your cluster.
Each instance of RuntimeComponent
CR represents the application to be deployed on the cluster:
apiVersion: rc.app.stacks/v1
kind: RuntimeComponent
metadata:
name: my-app
spec:
applicationImage: quay.io/my-repo/my-app:1.0
service:
type: ClusterIP
port: 9080
expose: true
statefulSet:
storage:
size: 2Gi
mountPath: "/logs"
The following table lists configurable fields of the RuntimeComponent
CRD. For complete OpenAPI v3 representation of these values, view the files under /deploy/releases/<operator-version>/kubectl/runtime-component-crd.yaml
. For example, the RuntimeComponent
CRD for release 0.8.2
.
Each RuntimeComponent
CR must at least specify the .spec.applicationImage
field. Specifying other fields is optional.
Field | Description |
---|---|
|
Configures pods to run on specific nodes. For examples, see Limit a pod to run on specified nodes. |
|
An array of architectures to be considered for deployment. Their position in the array indicates preference. |
|
A YAML object that represents a NodeAffinity. |
|
A YAML object that contains set of required labels and their values. |
|
A YAML object that represents a PodAffinity. |
|
A YAML object that represents a PodAntiAffinity. |
|
The absolute name of the image to be deployed, containing the registry and the tag. On OpenShift, it can also be set to |
|
The name of the application this resource is part of. If not specified, it defaults to the name of the CR. |
|
The current version of the application. Label |
|
Configures the wanted resource consumption of pods. For examples, see Configure multiple application instances for high availability. |
|
Required field for autoscaling. Upper limit for the number of pods that can be set by the autoscaler. It cannot be lower than the minimum number of replicas. |
|
Lower limit for the number of pods that can be set by the autoscaler. |
|
Target average CPU utilization (represented as a percentage of requested CPU) over all the pods. |
|
A Boolean to toggle the creation of Knative resources and use of Knative serving. To create a Knative service, set the parameter to true. For examples, see Deploy serverless applications with Knative and Expose applications externally. |
|
The wanted state and cycle of the deployment and resources owned by the deployment. |
|
Annotations to be added only to the deployment and resources owned by the deployment. |
|
A field to specify the update strategy of the deployment. For examples, see updateStrategy |
|
The type of update strategy of the deployment. The type can be set to |
|
DNS settings for the application pods. For more information, see Configure DNS |
|
The DNS Config for the application pods. |
|
The DNS Policy for the application pod. Defaults to ClusterFirst. |
|
Disable information about services being injected into the application pod as environment variables. The default value for this field is |
|
An array of environment variables following the format of |
|
An array of references to |
|
A boolean that toggles the external exposure of this deployment via a Route or a Knative Route resource. |
|
The list of Init Container definitions. |
|
A boolean to toggle automatic certificate generation and mounting TLS secret into the pod. The default value for this field is |
|
Specifies parameters for |
|
A YAML snippet representing an array of Endpoint component from ServiceMonitor. |
|
Labels to set on ServiceMonitor. |
|
Defines the network policy. For examples, see Allowing or limiting incoming traffic. |
|
A Boolean to disable the creation of the network policy. The default value is |
|
The labels of one or more pods from which incoming traffic is allowed. |
|
The labels of namespaces from which incoming traffic is allowed. |
|
Defines health checks on an application container to determine whether it is alive or ready to receive traffic. For examples, see Configure probes. |
|
A YAML object configuring the Kubernetes liveness probe that controls when Kubernetes needs to restart the pod. |
|
A YAML object configuring the Kubernetes readiness probe that controls when the pod is ready to receive traffic. |
|
A YAML object configuring the Kubernetes startup probe that controls when Kubernetes needs to startup the pod on its first initialization. |
|
The policy used when pulling the image. One of: |
|
If using a registry that requires authentication, the name of the secret containing credentials. |
|
The static number of desired replica pods that run simultaneously. |
|
The upper limit of CPU core. Specify integers, fractions (e.g. |
|
The memory upper limit in bytes. Specify integers with suffixes: |
|
The minimum required CPU core. Specify integers, fractions (e.g. |
|
The minimum memory in bytes. Specify integers with one of these suffixes: |
|
Annotations to be added to the |
|
A name of a secret that already contains TLS key, certificate and CA to be used in the |
|
Hostname to be used for the |
|
HTTP traffic policy with TLS enabled. Can be one of |
|
Path to be used for the |
|
Path type to be used. Required field for Ingress. See Ingress path types. |
|
TLS termination policy. Can be one of |
|
A security context to control privilege and permission settings for the application container. For examples, see Set privileges and permissions for a pod or container. If set, the fields of |
|
A Boolean that controls whether a process can gain more privileges than its parent process. This Boolean controls whether the |
|
The capabilities to add or drop when containers are run. Defaults to the default set of capabilities that the container runtime grants. |
|
An array of added capabilities of POSIX capabilities type. |
|
An array of removed capabilities of POSIX capabilities type. |
|
A Boolean to specify whether to run a container in privileged mode. Processes in privileged containers are equivalent to root on the host. The default is |
|
The type of proc mount to use for the containers. The default is |
|
A Boolean to specify whether this container has a read-only root file system. The default is |
|
The GID to run the entrypoint of the container process. If unset, |
|
A Boolean that specifies whether the container must run as a nonroot user. If |
|
The UID to run the entrypoint of the container process. If unset, the default is the user that is specified in image metadata. The value can be set in |
|
The SELinux context to be applied to the container. Its properties include |
|
The |
|
A profile that is defined in a file on the node. The profile must be preconfigured on the node to work. Specify a descending path, relative to the kubelet configured |
|
(Required) The kind of |
|
The Windows specific settings to apply to all containers. If unset, the options from the |
|
Configures parameters for the network service of pods. For an example, see Specify multiple service ports. |
|
Annotations to be added to the service. |
|
A boolean to toggle whether the operator expose the application as a bindable service. Defaults to |
|
Configure the TLS certificates for the service. The |
|
A name of a secret that already contains TLS key, certificate and CA to be mounted in the pod. The following keys are valid in the secret: |
|
Node proxies this port into your service. Please note once this port is set to a non-zero value it cannot be reset to zero. |
|
The port exposed by the container. |
|
An array consisting of service ports. |
|
The name for the port exposed by the container. |
|
The port that the operator assigns to containers inside pods. Defaults to the value of |
|
The Kubernetes Service Type. |
|
Deprecated. Use |
|
The service account to use for application deployment. If a service account name is not specified, a service account is automatically created. For examples, see Configure a service account. |
|
Name of the service account to use for deploying the application. |
|
A Boolean to toggle whether the service account’s token should be mounted in the application pods. If unset or |
|
The list of |
|
The wanted state and cycle of stateful applications. For examples, see Persist resources. |
|
Annotations to be added only to the StatefulSet and resources owned by the StatefulSet. |
|
The directory inside the container where this persisted storage will be bound to. |
|
A convenient field to set the size of the persisted storage. Can be overridden by the |
|
A YAML object representing a volumeClaimTemplate component of a |
|
A field to specify the update strategy of the StatefulSet. For examples, see updateStrategy |
|
The type of update strategy of the StatefulSet. The type can be set to |
|
Tolerations to be added to application pods. Tolerations allow the scheduler to schedule pods on nodes with matching taints. For more information, see Configure tolerations. |
|
A YAML object representing a pod volumeMount. For examples, see Persist Resources. |
|
A YAML object representing a pod volume. |
To deploy a Docker image that contains a runtime component to a Kubernetes environment, you can use the following CR:
apiVersion: rc.app.stacks/v1
kind: RuntimeComponent
metadata:
name: my-app
spec:
applicationImage: quay.io/my-repo/my-app:1.0
The applicationImage
value must be defined in the RuntimeComponent
CR. On OpenShift, the operator tries to find an image stream name with the applicationImage
value. The operator falls back to the registry lookup if it is not able to find any image stream that matches the value. If you want to distinguish an image stream called my-company/my-app
(project: my-company
, image stream name: my-app
) from the Docker Hub my-company/my-app
image, you can use the full image reference as docker.io/my-company/my-app
.
To get information on the deployed CR, use either of the following:
oc get runtimecomponent my-app
oc get comp my-app
The short name for runtimecomponent
is comp
.
An application administrator can view the status of an application that is deployed in a container. To get information about the deployed custom resource (CR), use a CLI or the Red Hat OpenShift console.
The status types for the .status.condition
parameter in the RuntimeComponent
CR are Ready
, ResourcesReady
, Reconciled
.
Reconciled
-
Indicates whether the current version of the operator successfully processed the configurations in the CR.
ResourcesReady
-
Indicates whether the application resources created and managed by the operator are ready.
Ready
-
Indicates the overall status of the application. If true, the application configuration was reconciled and its resource are in ready state.
To use the CLI to get information about a deployed CR, run a kubectl get
or oc get
command.
To run kubectl commands, you need the Kubernetes command line tool or the Red Hat OpenShift command-line interface (CLI). To run oc commands, you need the Red Hat OpenShift CLI.
In the following get commands, replace my-app
with your CR name. Run any one of the commands. comp
and comps
are short names for runtimecomponent
and runtimecomponents
.
-
Run any of the following
kubectl get
commands.
kubectl get comp my-app
kubectl get comps my-app
kubectl get runtimecomponent my-app
-
Run any of the following
oc get
commands.
oc get comp my-app
oc get comps my-app
oc get runtimecomponent my-app
The results of the command resemble the following.
NAME IMAGE EXPOSED RECONCILED RESOURCESREADY READY AGE
my-app quay.io/my-repo/my-app:1.0 True True True 18m
The value in the READY
column is True
when the application is successfully installed. If the value in the READY
column is not True
, see Troubleshooting Runtime Component operators.
To use the Red Hat OpenShift console to get information about a deployed CR, view the deployed RuntimeComponent
instance and inspect the .status
section.
status:
conditions:
- lastTransitionTime: '2022-05-10T15:59:04Z'
status: 'True'
type: Reconciled
- lastTransitionTime: '2022-05-10T15:59:16Z'
message: 'Deployment replicas ready: 3/3'
reason: MinimumReplicasAvailable
status: 'True'
type: ResourcesReady
- lastTransitionTime: '2022-05-10T15:59:16Z'
message: Application is reconciled and resources are ready.
status: 'True'
type: Ready
imageReference: 'quay.io/my-repo/my-app:1.0'
references:
svcCertSecretName: my-app-svc-tls-ocp
versions:
reconciled: 1.0.0
observedGeneration: 1
If the .status.conditions.type
Ready type does not have a status of True
, see Troubleshooting Runtime Component operators.
The value of the .status.versions.reconciled
parameter is the version of the operand that is deployed into the cluster after the reconcile loop completes.
At the end of the reconcile loop, the operator will also update the .status.observedGeneration
parameter to match the value of .metadata.generation
.
The operator controller periodically runs reconciliation to match the current state to the wanted state so that the managed resources remain functional. Runtime Component operator allows for increasing the reconciliation interval to reduce the controller’s workload when status remains unchanged. The reconciliation frequency can be configured with the Operator ConfigMap settings.
The value of the .status.conditions.unchangedConditionCount
parameter represents the number of reconciliation cycles during which the condition status type remains unchanged. Each time this value becomes an even number, the reconciliation interval increases according to the configurations in the ConfigMap
. The reconciliation interval increase feature is enabled by default but can be disabled if needed.
The .status.reconcileInterval
parameter represents the current reconciliation interval of the instance. The parameter increases by the increase percentage, which is specified in the ConfigMap
, based on the current interval. The calculation uses the base reconciliation interval, the increase percentage, and the count of unchanged status conditions, with the increases compounding over time. The maximum reconciliation interval is 240 seconds for repeated failures and 120 seconds for repeated successful status conditions.
The ConfigMap
named runtime-component-operator
is used for configuring the managed resources. It is created once when the operator starts and is located in the operator’s installed namespace.
For more information on ConfigMap configurations, see under Open Liberty Operator’s "Operator ConfigMap" section. Any references to Open Liberty Operator-specific resources can be mapped over to Runtime Component Operator using the table below.
Data |
Open Liberty Operator |
Runtime Component Operator |
Kind |
|
|
ConfigMap |
|
|
Browse the RuntimeComponent
examples to learn how to use custom resource (CR) parameters to configure your operator. The complete component documentation can be found under Open Liberty Operator’s "Common Component" section. Any references to Open Liberty Operator-specific resources can be mapped over to Runtime Component Operator using the table below.
Data |
Open Liberty Operator |
Runtime Component Operator |
Api Version |
|
|
Kind |
|
|
ConfigMap |
|
|
ClusterRole Prefix |
|
|
Resource Prefix |
|
|
-
Set environment variables for an application container (
.spec.env
or.spec.envFrom
) -
Configure multiple application instances for high availability (
.spec.replicas
or.spec.autoscaling
) -
Set privileges and permissions for a pod or container (
.spec.securityContext
) -
Persist resources (
.spec.statefulSet
and.spec.volumeMounts
) -
Specify multiple service ports (
.spec.service.port*
and.spec.monitoring.endpoints
) -
Deploy serverless applications with Knative (
.spec.createKnativeService
) -
Expose applications externally (
.spec.expose
,.spec.createKnativeService
,.spec.route
)
You can easily perform day-2 operations using the RuntimeOperation
custom resource (CR), which allows you to specify the commands to run on a container within a Pod.
Field |
Description |
|
The name of the Pod, which must be in the same namespace as the |
|
The name of the container within the Pod. The default value is the name of the main container, which is |
|
Command to run. The command doesn’t run in a shell. |
Example:
apiVersion: rc.app.stacks/v1
kind: RuntimeOperation
metadata:
name: example-runtime-operation
spec:
# Specify the name of the pod. The pod must be in the same namespace as this RuntimeOperation CR.
podName: Specify_Pod_Name_Here
# Specify the name of the container. The default value is the name of the main container, which is `app`.
containerName: app
# Run the following command. The command does not run in a shell.
command:
- /bin/sh
- '-c'
- echo "Hello" > /tmp/runtime-operation.log
You can check the status of a runtime operation by using the status
field inside the CR YAML file. You can also run the oc get runtimeop -o wide
command to see the status of all operations in the current namespace.
The operator will retry to run the RuntimeOperation
when it fails to start due to specified pod or container not being found or when the pod is not in running state. The retry interval will be doubled with each failed attempt.
Note
|
The RuntimeOperation CR must be created in the same namespace as the Pod to operate on. After the RuntimeOperation CR starts, the CR cannot be reused for more operations. A new CR needs to be created for each day-2 operation. The operator can process only one RuntimeOperation instance at a time. Long running commands can cause other runtime operations to wait before they start.
|
See the troubleshooting guide for information on how to investigate and resolve deployment problems.