Skip to content

Latest commit

 

History

History
297 lines (207 loc) · 7.75 KB

development.md

File metadata and controls

297 lines (207 loc) · 7.75 KB

Development Guide

Table of contents

Prerequisites

  • operator-sdk version v0.15.2
  • git
  • go version 1.13+
  • kubernetes version v1.13.0+
  • oc version v4.1+
  • Access to a Openshift v4.1.0+ cluster.
  • A user with administrative privileges in the OpenShift cluster.

Clone repository

mkdir -p $GOPATH/src/github.com/3scale
cd $GOPATH/src/github.com/3scale
git clone https://github.com/3scale/3scale-operator
cd 3scale-operator
git checkout master

Building 3scale operator image

Clone the repository

Build the operator image

make build IMAGE=quay.io/myorg/3scale-operator VERSION=test

Run 3scale Operator

Run 3scale Operator Locally

Run operator from the command line, it will not be deployed as a pod.

// As a cluster admin
for i in `ls deploy/crds/*_crd.yaml`; do oc create -f $i ; done
  • Create a new OpenShift project (optional)
export NAMESPACE=operator-test
oc new-project $NAMESPACE
  • Run operator
make local

Deploy 3scale Operator Manually

Build the operator image and deploy it manually as a pod.

make push IMAGE=quay.io/myorg/3scale-operator VERSION=test
  • Register the 3scale-operator CRDs in the OpenShift API Server
// As a cluster admin
for i in `ls deploy/crds/*_crd.yaml`; do oc create -f $i ; done
  • Create a new OpenShift project (optional)
export NAMESPACE=operator-test
oc new-project $NAMESPACE
  • Deploy the needed roles and ServiceAccounts
oc create -f deploy/service_account.yaml
oc create -f deploy/role.yaml
oc create -f deploy/role_binding.yaml
oc create -f deploy/cluster_role.yaml
oc create -f deploy/cluster_role_binding.yaml
  • Deploy the operator
sed -i 's|REPLACE_IMAGE|quay.io/myorg/3scale-operator:test|g' deploy/operator.yaml
oc create -f deploy/operator.yaml

Cleanup manually deployed operator

  • Delete all apimanager custom resources:
oc delete apimanagers --all
  • Delete the 3scale-operator operator, its associated roles and service accounts
oc delete -f deploy/operator.yaml
oc delete -f deploy/role_binding.yaml
oc delete -f deploy/service_account.yaml
oc delete -f deploy/role.yaml
# If 3scale-operator has been deployed in a cluster where other users might
# be using it do not delete the ClusterRole and ClusterRoleBinding below as
# they are shared global resources
oc delete -f deploy/cluster_role.yaml
oc delete -f deploy/cluster_role_binding.yaml
  • Delete the APIManager CRD:
oc delete crds apimanagers.apps.3scale.net

Deploy custom 3scale Operator using OLM

To install this operator on OpenShift 4 using OLM for end-to-end testing,

oc create -f deploy/olm-catalog/3scale-operatorsource.yaml

It will take a few minutes for the operator to become visible under the OperatorHub section of the OpenShift console Catalog. It can be easily found by filtering the provider type to Custom.

Run tests

Run unittests

No need access to OCP cluster

make unit
make test-crds

Run integration tests

Access to a Openshift v4.1.0+ cluster required

  • Run tests locally deploying the image
export NAMESPACE=operator-test
make e2e-run
  • Run tests locally running operator with go run instead of as an image in the cluster
export NAMESPACE=operator-test
make e2e-local-run

Building 3scale templates

Clone the repository

cd cd pkg/3scale/amp && make clean all

The location of the templates:

pkg/3scale/amp/auto-generated-templates

NOTE: If you want to use supported and stable templates you should go to the official repository

Manifest management

operator-courier is used for metadata syntax checking and validation. This can be installed directly from pip:

pip3 install operator-courier

Verify operator manifest

Check Required fields within your CSV

operator-courier will verify the fields included in the Operator metadata (CSV)

make verify-manifest

Push an operator bundle into external app registry

  • Get quay token

Detailed information on this guide

curl -sH "Content-Type: application/json" -XPOST https://quay.io/cnr/api/v1/users/login -d '{"user": {"username": "YOURUSERNAME", "password": "YOURPASSWORD"}}' | jq '.token'
  • Push bundle to Quay.io

Detailed information on this guide.

make push-manifest APPLICATION_REPOSITORY_NAMESPACE=YOUR_QUAY_NAMESPACE MANIFEST_RELEASE=1.0.0 TOKEN=YOUR_TOKEN

Licenses management

It is a requirement that a file describing all the licenses used in the product is included, so that users can examine it.

  • Check licenses when dependencies change.
make licenses-check
  • Update licenses.xml file.
make licenses.xml

Adding manually a new license

When licenses check does not parse correctly licensing information, it will complain. In that case, you need to add manually license information.

There are two options: a)specify dependency license (recommended) or b)add an exception for that dependency.

  • Specify dependency license:
license_finder dependencies add YOURLIBRARY --decisions-file=doc/dependency_decisions.yml LICENSE --project-path "PROJECT URL"

For instance

license_finder dependencies add k8s.io/klog --decisions-file=doc/dependency_decisions.yml "Apache 2.0" --project-path "https://github.com/kubernetes/klog"
  • Adding exception for a dependency:
license_finder approval add YOURLIBRARY --decisions-file=doc/dependency_decisions.yml --why "LICENSE_TYPE LINK_TO_LICENSE"

For instance

license_finder approval add github.com/golang/glog --decisions-file=doc/dependency_decisions.yml --why "Apache 2.0 License https://github.com/golang/glog/blob/master/LICENSE"