Deploy the open-cluster-management project

Welcome!

You might be asking yourself, "What is Open Cluster Management?", well it is the open-cluster-management project. View the open-cluster-management architecture diagram:

Architecture diagram

The GitHub org and project are currently distinct from the SaaS offering named "Red Hat OpenShift Cluster Manager" but will ultimately co-exist/share technology as needed. Core technology, such as Hive is already shared between the two offerings.

Kubernetes provides a platform to deploy and manage containers in a standard, consistent control plane. However, as application workloads move from development to production, they often require multiple fit-for-purpose Kubernetes clusters to support DevOps pipelines. Users such as administrators and site reliability engineers (SREs), face challenges as they work across a range of environments, including multiple data centers, private clouds, and public clouds that run Kubernetes clusters. The open-cluster-management project provides the tools and capabilities to address these common challenges.

open-cluster-management provides end-to-end visibility and control to manage your Kubernetes environment. Take control of your application modernization program with management capabilities for cluster creation, application lifecycle, and provide security and compliance for all of them across data centers and hybrid cloud environments. Clusters and applications are all visible and managed from a single console with built-in security policies. Run your operations where Red Hat OpenShift runs, and manage any Kubernetes cluster in your fleet.

With the open-cluster-management project, you can complete the following functionality tasks:

Work across a range of environments, including multiple data centers, private clouds and public clouds that run Kubernetes clusters.
Easily create Kubernetes clusters and offer cluster lifecycle management in a single console.
Enforce policies at the target clusters using Kubernetes-supported custom resource definitions.
Deploy and maintain day-two operations of business applications distributed across your cluster landscape.

Our code is open! To reach us in the open source community please head to https://open-cluster-management.io, and you can also find us on Kubernetes Slack workspace: https://kubernetes.slack.com/archives/C01GE7YSUUF

If you're looking for RHACM, the Red Hat multicluster management product that runs on OpenShift, your Red Hat account team rep should be able to help you get an evaluation of ACM so that you can use the actual product bits in a supported way. There is also a self-supported evaluation if you prefer that, and you can get started right away at: https://www.redhat.com/en/technologies/management/advanced-cluster-management -> click the “Try It” button.

Let's get started...

You can find our work-in-progress documentation here. Please read through the docs to find out how you can use the open-cluster-management project. Oh, and please submit an issue for any problems you may find, or clarifications you might suggest.

You can find information on how to contribute to this project and our docs project in our CONTRIBUTING.md doc.

Prereqs

You must meet the following requirements to install the open-cluster-management project:

An OpenShift Container Platform (OCP) 4.3+ cluster available
- You must have a default storage class defined
oc (ver. 4.3+) & kubectl (ver. 1.16+) configured to connect to your OCP cluster
oc is connected with adequate permissions to create new namespaces in your OCP cluster.
The following utilities required:
- sed
  - On macOS install using: brew install gnu-sed
- jq
  - On macOS install using: brew install jq
- yq (v4.12+)
  - On macOS install using: brew install yq
The following utilities are optional:
- watch
  - On macOS install using: brew install watch

Repo Structure and Organization

This repo contains the 3 directories:

prereqs - YAML definitions for prerequisite objects (namespaces and pull-secrets)
acm-operator - YAML definitions for setting up a CatalogSource for our operator
multiclusterhub - YAML definitions for creating an instance of MultiClusterHub

Each of the three directories contains a kustomization.yaml file that will apply the YAML definitions to your OCP instance with the following command: kubectl apply -k.

There are helper scripts in the root of this repo:

start.sh - takes the edge off having to manually edit YAML files
uninstall.sh - we're not perfect yet; includes additional scripting to ensure we clean up our mess on your OCP cluster.

You have multiple choices of installation:

the easy way - using the provided start.sh script which will assist you through the process.
the hard way - instructions to deploy open-cluster-management with only oc commands.
downstream images v2.0+ - instructions to deploy downstream images, i.e. for QE

Either way you choose to go, you are going to need a pull-secret in order to gain access to our built images residing in our private Quay environment. Please follow the instructions Prepare to deploy Open Cluster Management Instance to get your pull-secret setup.

Prepare to deploy Open Cluster Management Instance (only do once)

Clone this repo locally

git clone https://github.com/stolostron/deploy.git

Generate your pull-secret:
- ensure you have access to the quay org (stolostron)
- to request access to stolostron in quay.io, for external (non Red Hat) users, you can please contact the ACM BU via email at acm-contact@redhat.com. Or, if you have access to Red Hat Slack you can contact us on our Slack Channel #forum-hypbld) and indicate if you want upstream (stolostron) or downstream (acm-d) repos (or both). We'll need your quay ID. Once the team indicates they've granted you access, open your Notifications at quay.io and accept the invitation(s) waiting for you.
- you will also need a bot and token generated for each of the repositories you wish to use.
- acm-d (stolostron images are public)
- :exclamation: save secret file in the prereqs directory as pull-secret.yaml
- :exclamation: edit pull-secret.yaml file and change the name to multiclusterhub-operator-pull-secret
```
apiVersion: v1
kind: Secret
metadata:
  name: multiclusterhub-operator-pull-secret
...
```

Deploy using the ./start.sh script (the easy way)

We've added a very simple start.sh script to make your life easier. To deploy downstream images please refer to "Deploying downstream builds" section below.

First, you need to export KUBECONFIG=/path/to/some/cluster/kubeconfig (or do an oc login that will set it for you). deploy installs ACM to the cluster configured in your KUBECONFIG env variable.

Optionally export DEBUG=true for additional debugging output for 2.1+ releases. export USE_STARTING_CSV=true to use an explicit STARTING_CSV variable.

Running start.sh

Run the start.sh script. You have the following options when you run the command:

-t modify the YAML but exit before apply the resources
--silent, skip all prompting, uses the previous configuration
--watch, will monitor the main Red Hat ACM pod deployments for up to 10min
--search, will activate search as part of the deployment.

$ ./start.sh --watch --search

When prompted for the SNAPSHOT tag, either press Enter to use the previous tag, or provide a new SNAPSHOT tag.
- UPSTREAM snapshot tags - https://quay.io/repository/stolostron/acm-custom-registry?tab=tags
- DOWNSTREAM snapshot tag - https://quay.io/repository/acm-d/acm-dev-catalog?tab=tags
For example, your SNAPSHOT tag might resemble the following information:
```
2.0.5-SNAPSHOT-2020-10-26-21-38-29
```
NOTE: To change the default SNAPSHOT tag, edit snapshot.ver, which contains a single line that specifies the SNAPSHOT tag. This method of updating the default SNAPSHOT tag is useful when using the --silent option.
Depending on your script option choice, open-cluster-management will be deployed or deploying.

For version 2.1+, you can monitor the status fields of the multiclusterhub object created in the open-cluster-management namespace (namespace will differ if TARGET_NAMESPACE is set).

For version 2.0 and below, use watch oc -n open-cluster-management get pods to view the progress.
The script provides you with the Open Cluster Management URL.

Note: This script can be run multiple times and will attempt to continue where it left off. It is also good practice to run the uninstall.sh script if you have a failure and have installed multiple times.

Deploying Downstream Builds SNAPSHOTS for Product Quality Engineering (only 2.0+)

Requirements

Required Access

To deploy downstream builds, you need access to pull the related images from the downstream mirror respository, quay.io/acm-d. Access is internal to Red Hat only for Dev/Test/QE use. Contact us in Slack Channel #forum-hypbld on Red Hat

Deploy

Install / Use

README