Chapter 2. Preparing your OpenShift cluster
Chapter 2. Preparing your OpenShift cluster This chapter explains how to install Red Hat Integration - Camel K and OpenShift Serverless on OpenShift, and how to install the required Camel K and OpenShift Serverless command-line client tools in your development environment. Section 2.1, "Installing Camel K" Section 2.2, "Installing OpenShift Serverless" Section 2.3, "Configuring Maven repository for Camel K" Section 2.4, "Camel K offline" 2.1. Installing Camel K You can install the Red Hat Integration - Camel K Operator on your OpenShift cluster from the OperatorHub. The OperatorHub is available from the OpenShift Container Platform web console and provides an interface for cluster administrators to discover and install Operators. After you install the Camel K Operator, you can install the Camel K CLI tool for command line access to all Camel K features. Prerequisites You have access to an OpenShift 4.6 (or later) cluster with the correct access level, the ability to create projects and install operators, and the ability to install CLI tools on your local system. Note You installed the OpenShift CLI tool ( oc ) so that you can interact with the OpenShift cluster at the command line. For details on how to install the OpenShift CLI, see Installing the OpenShift CLI . Procedure In the OpenShift Container Platform web console, log in by using an account with cluster administrator privileges. Create a new OpenShift project: In the left navigation menu, click Home > Project > Create Project . Enter a project name, for example, my-camel-k-project , and then click Create . In the left navigation menu, click Operators > OperatorHub . In the Filter by keyword text box, type Camel K and then click the Red Hat Integration - Camel K Operator card. Read the information about the operator and then click Install . The Operator installation page opens. Select the following subscription settings: Update Channel > latest Choose among the following 2 options: Installation Mode > A specific namespace on the cluster > my-camel-k-project Installation Mode > All namespaces on the cluster (default) > Openshift operator Note Approval Strategy > Automatic Note The Installation mode > All namespaces on the cluster and Approval Strategy > Manual settings are also available if required by your environment. Click Install , and wait a few moments until the Camel K Operator is ready for use. Download and install the Camel K CLI tool: From the Help menu (?) at the top of the OpenShift web console, select Command line tools . Scroll down to the kamel - Red Hat Integration - Camel K - Command Line Interface section. Click the link to download the binary for your local operating system (Linux, Mac, Windows). Unzip and install the CLI in your system path. To verify that you can access the Kamel K CLI, open a command window and then type the following: kamel --help This command shows information about Camel K CLI commands. Note If you uninstall the Camel K operator from OperatorHub using OLM, the CRDs are not removed. To shift back to a Camel K operator, you must remove the CRDs manually by using the following command. oc get crd -l app=camel-k -o name | xargs oc delete step (optional) Specifying Camel K resource limits 2.1.1. Consistent integration platform settings You can create namespace local Integration Platform resources to overwrite settings used in the operator. These namespace local platform settings must be derived from the Integration Platform being used by the operator by default. That is, only explicitly specified settings overwrite the platform defaults used in the operator. Therefore, you must use a consistent platform settings hierarchy where the global operator platform settings always represent the basis for user specified platform settings. In case of global Camel K operator, if IntegrationPlatform specifies non-default spec.build.buildStrategy, this value is also propagated to namespaced Camel-K operators installed thereafter. Default value for buildStrategy is routine. USD oc get itp camel-k -o yaml -n openshift-operators apiVersion: camel.apache.org/v1 kind: IntegrationPlatform metadata: labels: app: camel-k name: camel-k namespace: openshift-operators spec: build: buildStrategy: pod The parameter buildStrategy of global operator IntegrationPlatform can be edited by one of the following ways; From Dashboard Administrator view: Operators Installed operators in namespace openshift-operators (that is, globally installed operators), select Red Hat Integration - Camel K Integration Platform YAML Now add or edit (if already present) spec.build.buildStrategy: pod Click Save Using the following command. Any namespaced Camel K operators installed subsequently would inherit settings from the global IntegrationPlatform. oc patch itp/camel-k -p '{"spec":{"build":{"buildStrategy": "pod"}}}' --type merge -n openshift-operators 2.1.2. Specifying Camel K resource limits When you install Camel K, the OpenShift pod for Camel K does not have any limits set for CPU and memory (RAM) resources. If you want to define resource limits for Camel K, you must edit the Camel K subscription resource that was created during the installation process. Prerequisite You have cluster administrator access to an OpenShift project in which the Camel K Operator is installed as described in Installing Camel K . You know the resource limits that you want to apply to the Camel K subscription. For more information about resource limits, see the following documentation: Setting deployment resources in the OpenShift documentation. Managing Resources for Containers in the Kubernetes documentation. Procedure Log in to the OpenShift Web console. Select Operators > Installed Operators > Operator Details > Subscription . Select Actions > Edit Subscription . The file for the subscription opens in the YAML editor. Under the spec section, add a config.resources section and provide values for memory and cpu as shown in the following example: Save your changes. OpenShift updates the subscription and applies the resource limits that you specified. Important We recommend you to install Camel K Operator through Global installtion only. 2.2. Installing OpenShift Serverless You can install the OpenShift Serverless Operator on your OpenShift cluster from the OperatorHub. The OperatorHub is available from the OpenShift Container Platform web console and provides an interface for cluster administrators to discover and install Operators. The OpenShift Serverless Operator supports both Knative Serving and Knative Eventing features. For more details, see installing OpenShift Serverless Operator . Prerequisites You have cluster administrator access to an OpenShift project in which the Camel K Operator is installed. You installed the OpenShift CLI tool ( oc ) so that you can interact with the OpenShift cluster at the command line. For details on how to install the OpenShift CLI, see Installing the OpenShift CLI . Procedure In the OpenShift Container Platform web console, log in by using an account with cluster administrator privileges. In the left navigation menu, click Operators > OperatorHub . In the Filter by keyword text box, enter Serverless to find the OpenShift Serverless Operator . Read the information about the Operator and then click Install to display the Operator subscription page. Select the default subscription settings: Update Channel > Select the channel that matches your OpenShift version, for example, 4.16 Installation Mode > All namespaces on the cluster Approval Strategy > Automatic Note The Approval Strategy > Manual setting is also available if required by your environment. Click Install , and wait a few moments until the Operator is ready for use. Install the required Knative components using the steps in the OpenShift documentation: Installing Knative Serving Installing Knative Eventing (Optional) Download and install the OpenShift Serverless CLI tool: From the Help menu (?) at the top of the OpenShift web console, select Command line tools . Scroll down to the kn - OpenShift Serverless - Command Line Interface section. Click the link to download the binary for your local operating system (Linux, Mac, Windows) Unzip and install the CLI in your system path. To verify that you can access the kn CLI, open a command window and then type the following: kn --help This command shows information about OpenShift Serverless CLI commands. For more details, see the OpenShift Serverless CLI documentation . Additional resources Installing OpenShift Serverless in the OpenShift documentation 2.3. Configuring Maven repository for Camel K For Camel K operator, you can provide the Maven settings in a ConfigMap or a secret. Procedure To create a ConfigMap from a file, run the following command. Created ConfigMap can be then referenced in the IntegrationPlatform resource, from the spec.build.maven.settings field. Example Or you can edit the IntegrationPlatform resource directly to reference the ConfigMap that contains the Maven settings using following command: Configuring CA certificates for remote Maven repositories You can provide the CA certificates, used by the Maven commands to connect to the remote Maven repositories, in a Secret. Procedure Create a Secret from file using following command: Reference the created Secret in the IntegrationPlatform resource, from the spec.build.maven.caSecret field as shown below. 2.4. Camel K offline Camel K is naturally developed to fit in an "open world" cluster model. It means that the default installation assumes it can pull and push resources from the Internet. However, there can be certain domains or use cases where this is a limitation. The following are the details about how to setup Camel K in an offline (or disconnected, or air gapped) cluster environment. Requirements Install Camel K 1.10.7 in a disconnected openshift 4.14+ cluster in OLM mode. Run integrations in the same cluster by using a maven repository manager to serve the maven artifacts. Note Out of scope Support install and management of a maven repository manager. Mount volumes with the maven artifacts Use the --offline maven parameter. How to install or configure OCP in disconnected environments. Assumption An existing OCP 4.14+ cluster configured in a disconnected environment . An existing container image registry. An existing maven repository manager. Execute the command steps in a linux machine. Prerequisites You are familiar with Camel K network architecture . Let us see the diagram here. We can identify those components which requires access to the Internet and treat them separately: the image registry and the maven builds. 2.4.1. Container images registry The container registry is the component in charge to host the containers which are built from the operator and are used by the cluster to run the Camel applications. This component can be provided out of the box by the cluster, or should be operated by you (see the guide on how to run your own registry ). As we are in a disconnected environment, we assume this component to be accessible by the cluster (through an IP or URL). However, the cluster must use the Camel K container image , in order to be installed. You must ensure that the cluster registry has preloaded the Camel K container image, which should be similar to registry.redhat.io/integration/camel-k-rhel8-operator-bundle:1.10.7 Note Red Hat container images are defined in the ecosystem catalog see Get this image tab, then you see the container image digest address, in the Manifest List Digest field: Openshift provides documentation to mirror container images . When mirroring the container images, you must ensure to include the following container images that are required by Camel K during its operations, note that, in a disconnected cluster we have to use the digest URLs and not the tag. For container images provided by Red Hat, visit the Red Hat ecosystem catalog , find the container image and copy the digest URL of the container image. registry.redhat.io/integration/camel-k-rhel8-operator:1.10.7 registry.redhat.io/integration/camel-k-rhel8-operator-bundle:1.10.7 registry.redhat.io/quarkus/mandrel-23-rhel8:23.0 registry.access.redhat.com/ubi8/openjdk-11:1.20 An example of a digest URL of Camel K 1.10.7: registry.redhat.io/integration/camel-k-rhel8-operator-bundle@sha256:a043af04c9b816f0dfd5db64ba69bae192d73dd726df83aaf2002559a111a786 If all the above is set, then, you must be ready to pull and push from the container registry in Camel K as well. 2.4.1.1. Creating your own CatalogSource The only supported way to install Camel K operator is from OperatorHub. Since we use a disconnected environment, the container images from the redhat-operators CatalogSource cannot be downloaded. For that reason, we must create our own CatalogSource to install the Camel K operator from OperatorHub. Note There is mirroring of the Operator Catalog , to mirror a CatalogSource. However, there is this way to set up a custom CatalogSource with only the Camel K Bundle Metadata container image. Prerequisites Required tools Opm: https://github.com/operator-framework/operator-registry/releases Podman: https://podman.io/docs/installation Images accessible on your registry Camel K Operator and Camel K Operator Bundle with sha256 tag. 2.4.1.1.1. Creating own Index Image Bundle (IIB) Firstly, we need to create our own IIB image with only one operator inside. Note No operator upgrade is possible. Setup Create IIB locally with only one bundle (use sha tag): For example: opm index add --bundles registry.redhat.io/integration/camel-k-rhel8-operator-bundle@sha256:a043af04c9b816f0dfd5db64ba69bae192d73dd726df83aaf2002559a111a786 --tag my-custom-registry/mygroup/ck-iib:1.10.7 --mode=semver Check if the image was created. Push to your registry. For example: podman push my-custom-registry/mygroup/ck-iib:1.10.7 Additional resource Building an index of Operators using opm 2.4.1.1.2. Creating own catalog source Create yaml file, that is, myCatalogSource.yaml with content: apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: {CATALOG_SOURCE_NAME} namespace: openshift-marketplace spec: displayName: {NAME_WHICH_WILL_BE_DISPLAYED_IN_OCP} publisher: grpc sourceType: grpc image: {YOUR_CONTAINER_STORAGE}/{USERNAME}/{IMAGE_NAME}:{SHA_TAG}} For example; apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: camel-k-source-1.10 namespace: openshift-marketplace spec: displayName: Camel K Offline publisher: grpc sourceType: grpc image: ec2-1-111-111-111.us-east-1.compute.amazonaws.com:5000/myrepository/ckiib@sha256:f67fc953b10729e49bf012329fbfb6352b91bbc7d4b1bcdf5779f6d31c397c5c Login to your Openshift with oc tool: Oc login -u {USER} -p {PASS} https://api.{YOUR_CLUSTER_API_URL}:6443 Deploy CatalogSource to openshift-marketplace namespace: oc apply -f myCatalogSource.yaml -n openshift-marketplace Open your Openshift web console, navigate to OperatorHub, select the Camel K Offline Source, then on the right side, select "Red Hat Integration - Camel K" and install it. 2.4.2. Maven build configuration Warning This guide is a best effort development done to help the final user to create maven offline bundle and be able to run Camel K in offline mode. However, since the high degree of flexibility in the installation topology we cannot provide any level of support, only guidance on the possible configuration to adopt. Also, given the quantity of third party dependencies downloaded during the procedure we cannot ensure any protection against possible CVEs affecting these third party libraries. Use at your best convenience. The procedure contains a script that resolves, downloads and packages the entire set of Camel K Runtime and their transitive dependencies required by Maven to build and run the camel integration. It requires that the Maven version from where you are running the scripts (likely your machine) is the same used in the Camel K operator, that is, Maven 3.6.3, This will ensure to have the correct dependencies versions. Important The operator expects the dependencies to be owned by 1001 user. So ensure that the script is executed by such a user to avoid the maven build to fail due to privilege faults. The output of the script is a tar.gz file containing all the tree of dependencies expected by Maven, allowing the target building system (that is, the Camel K operator). Note It may not work in Quarkus native mode as the native build may require additional dependencies not available in the bundle. 2.4.2.1. Offliner script The script is available in Camel K github repository . You can run like this: ./offline_dependencies.sh usage: ./script/offline_dependencies.sh -v <Camel K Runtime version> [optional parameters] -v <Camel K Runtime version> - Camel K Runtime Version -m </usr/share/bin/mvn> - Path to mvn command -r <http://my-repo.com> - URL address of the maven repository manager -d </var/tmp/offline-1.2> - Local directory to add the offline dependencies -s - Skip Certificate validation An example of a sample run: ./offline_dependencies.sh -v 1.15.6.redhat-00029 -r https://maven.repository.redhat.com/ga -d camel-k-offline -s How to know the correct Camel K Runtime version ? You should look at the IntegrationPlatform/camel-k custom resource object in the Openshift cluster, look for the runtimeVersion field, example: It may take about 30 minutes to resolve, if there is a maven proxy. All the packaged dependencies are available in a tar.gz file. It is a big file as it contains all the transitive dependencies required by all Camel components configured in the camel-k-catalog. 2.4.2.2. Upload dependencies to the the Maven Proxy Manager The best practice we suggest is to always use a Maven Proxy. This is also the case of an offline installation. In such case you can check your Maven Repository Manager documentation and verify how to upload dependencies using the file created in the chapter above. When you build the integration route, the build should use the maven proxy, thus requiring a custom maven settings.xml configured to mirror all maven repositories to go through the maven proxy. Get the URL of the maven proxy and set in the url field, like the example below: <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> <mirrors> <mirror> <id>local-central-mirror</id> <name>local-central-mirror</name> <mirrorOf>*</mirrorOf> <url>http://my-maven-proxy:8080/releases</url> </mirror> </mirrors> </settings> Create a ConfigMap from this maven settings.xml. Now you have to inform Camel K to use this settings.xml when building the integrations. If you have already installed Camel K, then you can patch the IntegrationPlatform/camel-k , verify you environment for custom name and namespace: kubectl patch itp/camel-k --type=merge -p '{"spec": {"build": {"maven": {"settings": {"configMapKeyRef": {"key": "settings.xml", "name": "local-maven-settings-offline"}}}}}}' Then you should be able to run the integration with kamel run my-integration.java and follow the camel-k-operator log. 2.4.2.3. Troubleshooting 2.4.2.3.1. Error to download dependencies Check if the maven repository manager is reachable from the camel-k-operator log. Get into the camel-k-operator log And use curl to download the maven artifact 2.4.2.3.2. Dependency not found It may happen that a specific maven artifact is not found in the maven proxy manager, due to the offline script inability to resolve and download the dependency, so you have to download that dependency and upload to the maven proxy manager.
You do not need to create a pull secret when installing Camel K from the OpenShift OperatorHub. The Camel K Operator automatically reuses the OpenShift cluster-level authentication to pull the Camel K image from `registry.redhat.io`. If you do not choose among the above two options, the system by default chooses a global namespace on the cluster then leading to openshift operator. oc get itp camel-k -o yaml -n openshift-operators apiVersion: camel.apache.org/v1 kind: IntegrationPlatform metadata: labels: app: camel-k name: camel-k namespace: openshift-operators spec: build: buildStrategy: pod patch itp/camel-k -p '{"spec":{"build":{"buildStrategy": "pod"}}}' --type merge -n openshift-operators spec: channel: default config: resources: limits: memory: 512Mi cpu: 500m requests: cpu: 200m memory: 128Mi create configmap maven-settings --from-file=settings.xml apiVersion: camel.apache.org/v1 kind: IntegrationPlatform metadata: name: camel-k spec: build: maven: settings: configMapKeyRef: key: settings.xml name: maven-settings edit itp camel-k create secret generic maven-ca-certs --from-file=ca.crt apiVersion: camel.apache.org/v1 kind: IntegrationPlatform metadata: name: camel-k spec: build: maven: caSecret: key: tls.crt name: tls-secret opm index add --bundles {CAMEL_K_OPERATOR_BUNDLE_WITH_SHA_TAG} --tag {YOUR_CONTAINER_STORAGE}/{USERNAME}/{IMAGE_NAME}:{TAG} --mode=semver opm index add --bundles registry.redhat.io/integration/camel-k-rhel8-operator-bundle@sha256:a043af04c9b816f0dfd5db64ba69bae192d73dd726df83aaf2002559a111a786 --tag my-custom-registry/mygroup/ck-iib:1.10.7 --mode=semver images push {YOUR_CONTAINER_STORAGE}/{USERNAME}/{IMAGE_NAME}:{TAG} push my-custom-registry/mygroup/ck-iib:1.10.7 apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: {CATALOG_SOURCE_NAME} namespace: openshift-marketplace spec: displayName: {NAME_WHICH_WILL_BE_DISPLAYED_IN_OCP} publisher: grpc sourceType: grpc image: {YOUR_CONTAINER_STORAGE}/{USERNAME}/{IMAGE_NAME}:{SHA_TAG}} apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: camel-k-source-1.10 namespace: openshift-marketplace spec: displayName: Camel K Offline publisher: grpc sourceType: grpc image: ec2-1-111-111-111.us-east-1.compute.amazonaws.com:5000/myrepository/ckiib@sha256:f67fc953b10729e49bf012329fbfb6352b91bbc7d4b1bcdf5779f6d31c397c5c Oc login -u {USER} -p {PASS} https://api.{YOUR_CLUSTER_API_URL}:6443 apply -f myCatalogSource.yaml -n openshift-marketplace ./offline_dependencies.sh usage: ./script/offline_dependencies.sh -v <Camel K Runtime version> [optional parameters] -v <Camel K Runtime version> - Camel K Runtime Version -m </usr/share/bin/mvn> - Path to mvn command -r <http://my-repo.com> - URL address of the maven repository manager -d </var/tmp/offline-1.2> - Local directory to add the offline dependencies -s - Skip Certificate validation ./offline_dependencies.sh -v 1.15.6.redhat-00029 -r https://maven.repository.redhat.com/ga -d camel-k-offline -s get integrationplatform/camel-k -oyaml|grep runtimeVersion <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> <mirrors> <mirror> <id>local-central-mirror</id> <name>local-central-mirror</name> <mirrorOf>*</mirrorOf> <url>http://my-maven-proxy:8080/releases</url> </mirror> </mirrors> </settings> create configmap local-maven-settings-offline --from-file=settings.xml=maven-settings-offline.xml patch itp/camel-k --type=merge -p '{"spec": {"build": {"maven": {"settings": {"configMapKeyRef": {"key": "settings.xml", "name": "local-maven-settings-offline"}}}}}}' logs -f `kubectl get pod -l app=camel-k -oname` -n openshift-operators exec -i -t `kubectl -n openshift-operators get pod -l app=camel-k -oname` -- bash curl http://my-maven-proxy:8080/my-artifact.jar -o file