OpenShift Agent providers are a pair of CAPI providers, bootstrap and controlplane, which objective is to install OpenShift on BareMetal.

OpenShift Agent providers install OpenShift on BareMetal without the need of a bootstrap node. To achieve this feature, the providers are using Assisted Installer ZTP flow behind the scenes.

• CAPM3

• go version v1.21.0+
• docker version 17.03+.
• kubectl version v1.11.3+.
• Access to a Kubernetes v1.11.3+ cluster.

To configure clusterctl with the OpenShift Agent providers, edit ~/.cluster-api/clusterctl.yaml and add the following:

  - name: "openshift-agent"
    url: "https://github.com/openshift-assisted/cluster-api-agent/releases/latest/download/bootstrap-components.yaml"
    type: "BootstrapProvider"
  - name: "openshift-agent"
    url: "https://github.com/openshift-assisted/cluster-api-agent/releases/latest/download/controlplane-components.yaml"
    type: "ControlPlaneProvider"

After this we will be able to initialize clusterctl:

clusterctl init --bootstrap openshift-agent --control-plane openshift-agent -i  metal3:v1.7.0

Host data will be injected in the host through environment variables. We can use them as shown below:

nodeRegistration:
  name: '${METADATA_NAME}'
  kubeletExtraLabels:
  - 'metal3.io/uuid="${METADATA_NMETAL3_NAMESPACE}/${METADATA_NMETAL3_NAME}/${METADATA_UUID}"'

Detailed architecture design

Build and push your image to the location specified by IMG:

make docker-build docker-push IMG=<some-registry>/cluster-api-agent:tag

NOTE: This image ought to be published in the personal registry you specified. And it is required to have access to pull the image from the working environment. Make sure you have the proper permission to the registry if the above commands don’t work.

Install the CRDs into the cluster:

make install-all

Deploy the Manager to the cluster with the image specified by IMG:

make deploy IMG=<some-registry>/cluster-api-agent:tag

NOTE: If you encounter RBAC errors, you may need to grant yourself cluster-admin privileges or be logged in as admin.

Create instances of your solution You can apply the samples (examples) from the config/sample:

kubectl apply -k config/samples/

NOTE: Ensure that the samples has default values to test it out.

This provider is configured to deploy on Red Hat OpenShift (OCP) by default.

To deploy this provider on vanilla Kubernetes, the following must be done:

A vanilla Kubernetes such as Kind must be deployed and you must be authenticated to the cluster.

In addition to the prerequisites section above, the following services are required on your cluster before installing this provider.

1. Install Assisted-Service operator
2. Install CAPI
3. Install CAPM3

The following CLI tools are required:

1. kustomize

Create kustomize files for the providers

Bootstrap Provider

mkdir -p bootstrap
cat <<EOF > bootstrap/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- https://github.com/openshift-assisted/cluster-api-agent/bootstrap/config/default?ref=master

patches:
- patch: |-
    - op: add
      path: "/spec/template/spec/containers/1/env/-"
      value:
        name: USE_INTERNAL_IMAGE_URL
        value: "true"
  target:
    group: apps
    version: v1
    kind: Deployment
    namespace: system
    name: controller-manager
EOF

NOTE: The path for the patch is fragile, ensure that the container index is correct.

The overrides listed in the Configuration section below can also be patched here.

Control Plane Provider

mkdir -p controlplane
cat <<EOF > controlplane/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- https://github.com/openshift-assisted/cluster-api-agent/controlplane/config/default?ref=master
EOF

Run the following to define and create the CRs for the controllers:

kustomize build bootstrap > bootstrap_config.yaml
kustomize build controlplane > controlplane_config.yaml

kubectl apply -f bootstrap_config.yaml
kubectl apply -f controlplane_config.yaml

The following environment variables can be overridden for the bootstrap provider:

Delete the instances (CRs) from the cluster:

kubectl delete -k config/samples/

Delete the APIs(CRDs) from the cluster:

make uninstall

UnDeploy the controller from the cluster:

make undeploy

Following are the steps to build the installer and distribute this project to users.

1. Build the installer for the image built and published in the registry:

make build-installer IMG=<some-registry>/cluster-api-agent:tag

NOTE: The makefile target mentioned above generates an 'install.yaml' file in the dist directory. This file contains all the resources built with Kustomize, which are necessary to install this project without its dependencies.

2. Using the installer

Users can just run kubectl apply -f to install the project, i.e.:

kubectl apply -f https://raw.githubusercontent.com/<org>/cluster-api-agent/<tag or branch>/dist/install.yaml

E2E tests can be executed through ansible tasks in a target remote host.

Export the following env vars:

SSH_KEY_FILE path to the private SSH key file to access the remote host SSH_AUTHORIZED_KEY value of your public SSH key which is used to access the hosts used for deploying the workload cluster REMOTE_HOST remote host name where to execute the tests: root@<REMOTE_HOST> PULLSECRET base64-encoded pull secret to inject into the tests DIST_DIR is this repository directory /dist i.e. $(pwd)/dist CONTAINER_TAG is the tag of the controller images built and deployed in the testing environment. Defaults to local if unset.

Run the following to generate all the manifests before starting:

make generate && make manifests && make build-installer

Then we can run:

make e2e-test

Run:

make ansible-lint

• 001-distribution-version
• 002-distribution-version-upgrades

Please, read our CONTRIBUTING guidelines for more info about how to create, document, and review PRs.

Copyright 2024.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.