Toolchain Operator

Operator to enable CodeReady Toolchain on OSD clusters

Table of Contents

• 1. Overview
• 2. Building from source
  • 2.1. Prerequisites
  • 2.2. Get the code
  • 2.3. Build
• 3. Running On Minishift
• 4. Developer
  • 4.1. Code formatting
• 5. Running on Minishift(v1.25.0)
  • 5.1. Start minishift and logged in as cluster-admin
  • 5.2. Installing OLM
• 6. Running in Openshift 4.x
  • 6.1. Login as cluster-admin

1. Overview

To enable CodeReady Toolchain on any Openshift cluster, we need one time configuration setup which includes following things:

• Service Account with required roles

  • Create service account toolchain-sre.

  • Create dsaas-cluster-admin clusterrole.

  • Bind self-provisioner and dsaas-cluster-admin clusterrole to toolchain-sre service account.

• OAuth Client

  • Create oauthclient with secret and redirect uris and other required parameters

• Cluster Configuration

  • Find routing subdomain.

  • Find cluster name.

  • Find cluster’s public url.

• Update Cluster Management Service with above cluster configuration

  • Get required token from auth service

  • Post cluster configuration with valid token to cluster management service.

• Pre-requisites for manage.openshift.com

  • Create service account online-registration in openshift-infra namespace for manage.openshift.com

  • Create cluster role online-registration and bind it to online-registration service account.

• (ToDo) Create image-puller Daemonset for che.

As mentioned above operator will update cluster information to the cluster management service, so that it can provision namespaces/projects to required users on this new cluster.

So in short this operator has to create required resources, find required cluster configuration details and update it to cluster management service.

Btw, cluster management service is interested in following information.

{
       "name":"us-east-2",
       "api-url":"https://api.starter-us-east-2.openshift.com",
       "app-dns":"8a09.starter-us-east-2.openshiftapps.com",
       "service-account-token":"fX0nH3d68LQ6SK5wBE6QeKJ6X8AZGVQO3dGQZZETakhmgmWAqr2KDFXE65KUwBO69aWoq",
       "service-account-username":"dsaas",
       "token-provider-id":"f867ac10-5e05-4359-a0c6-b855ece59090",
       "auth-client-id":"autheast2",
       "auth-client-secret":"autheast2secret",
       "auth-client-default-scope":"user:full"
}

2. Building from source

The following guide is mainly targeted towards a Linux machine.

2.1. Prerequisites

You need to install:

• go (>= v1.11)

• git

• mercurial

• make

• operator-sdk (>= v0.4.0)

2.1.1. Check your Go version

Run the following command to find out your Go version.

$ go version

You must at least have Go version 1.11.

See Fetch dependencies to see an explanaition on how we deal with dependencies.

2.1.2. Install dep

This project uses dep as a package manager for Go. Running the make deps command will install dep in $GOPATH/bin if it’s not already available on your system.

2.1.3. Installing Operator-SDK

Follow this guide to install operator-sdk

2.2. Get the code

Assuming you have Go installed and configured (have $GOPATH setup) here is how to build.

Check out the code

$ git clone https://github.com/fabric8-services/toolchain-operator $GOPATH/src/github.com/fabric8-services/toolchain-operator

2.3. Build

Like most other projects, this one depends on various other projects that need to be downloaded.

To fetch the dependencies and finally build the project you can type make build in a freshly clone repository of this project.

$ cd $GOPATH/src/github.com/fabric8-services/toolchain-operator
$ make build

2.3.1. Special make targets

There is no need to fetch the dependencies, or re-generate code every time you want to compile. That’s why we offer special make targets for these topics:

• Fetch dependencies

• Build

• Clean

• Tests

Fetch dependencies

This will download all the dependencies for this project inside a directory called vendor. This way we can ensure that every developer and our CI system is using the same version.

$ cd $GOPATH/src/github.com/fabric8-services/toolchain-operator
$ make deps

For dependency management of go packages we use dep.

The file Gopkg.toml contains all dependencies. If you want to understand the format for this file, look here.

Build

If you want to just build the toolchain operator, run make build.

$ cd $GOPATH/src/github.com/fabric8-services/toolchain-operator
$ make build

Clean

This removes all downloaded dependencies, all generated code and compiled artifacts.

$ cd $GOPATH/src/github.com/fabric8-services/toolchain-operator
$ make clean

Tests

Here’s how to run all available tests. All tests will check all Go packages except those in the vendor/ directory.

unit-tests

Unit tests have the minimum requirement on time and environment setup.

cd $GOPATH/src/github.com/fabric8-services/toolchain-operator
make test-unit

e2e-tests

TL; DR

make minishift-start
eval $(minishift docker-env)
cd $GOPATH/src/github.com/fabric8-services/toolchain-operator
make test-e2e

E2E tests are verifying successful deployment of Toolchain Operator and creation of required resources. End To end tests demand openshift cluster to be up and running.

However you can run minishift which is single node openshift cluster. You can check it using minishift status. If not then start it using make minishift-start target.

After successfully starting minishift, configure your shell to use docker daemon from minishift using eval $(minishift docker-env).

Now it’s time to run E2E tests for toolchain-operator which will create it’s required resources from deploy/test/ on OpenShift use following command:

make test-e2e

This make target is building new docker image $(DOCKER_REPO)/$(IMAGE_NAME):test(e.g. quay.io/openshiftio/toolchain-operator:test) which is used in the operator’s deployment manifests in e2e tests.

Also remember that it uses the system:admin account for creating all required resources from deploy/test directory.

all

To run both, the unit and the end to end tests you can run

$ cd $GOPATH/src/github.com/fabric8-services/toolchain-operator
$ make test-all

3. Running On Minishift

Follow minishift guide to run operator on minishift

4. Developer

4.1. Code formatting

To check if the code is properly formatted run:

$ make check-go-format

To format the code:

$ make format-go-code

5. Running on Minishift(v1.25.0)

5.1. Start minishift and logged in as cluster-admin

minishift start --cpus 4 --memory 8GB

oc login -u system:admin

5.2. Installing OLM

oc apply -f https://raw.githubusercontent.com/operator-framework/operator-lifecycle-manager/master/deploy/upstream/quickstart/olm.yaml

docs/set_env_build_push_registry.adoc

docs/run_operator_using_olm.adoc

6. Running in Openshift 4.x

To ship toolchain-operator from marketplace, we are bundling operator manifests with our own registry, where cluster-admin can create CatalogSource if needed and find our operator in operator catalogs.

We don’t want to ship our operator to every cluster by default, this is why we are not going with default operatorsources which creates catalogsource for Community, RedHat, Certified operator registry.

docs/set_env_build_push_registry.adoc

6.1. Login as cluster-admin

Make sure that you have logged in as cluster-admin to do following steps.

docs/run_operator_using_olm.adoc