3scale-operator
This software is licensed under the Apache 2.0 license.
See the LICENSE and NOTICE files that should have been provided along with this software for details.
Project Status: alpha
The project is currently alpha which means that there are still new feautres
and APIs planned that will be added in the future.
Due to this, breaking changes may still happen.
Only use for short-lived testing clusters. Do not deploy it in the same
OpenShift project than one having an already existing
3scale API Management solution, as it could potentially alter/delete the
existing elements in the project.
Overview
This project contains the 3scale operator software. 3scale operator is a
software based on Kubernetes operators that
provides:
- A way to install a 3scale API Management solution, providing configurability
options at the time of installation
- Ability to define 3scale API definitions and set
them into a 3scale API Management solution
This functionalities definitions are provided via Kubernetes custom resources
that the operator is able to understand and process.
Prerequisites
- operator-sdk version v0.8.0.
- git
- go version 1.12.5+
- kubernetes version v1.11.0+
- oc version v3.11+
- Access to a Openshift v3.11.0+ cluster.
- A user with administrative privileges in the OpenShift cluster.
Getting started
Download the 3scale-operator project:
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
Create and deploy a 3scale-operator and the custom resources needed
to install a sample 3scale API Management solution and API definitions:
# As an OpenShift administrative user create the 3scale-operator CRDs:
for i in `ls deploy/crds/*_crd.yaml`; do oc create -f $i ; done
# Create a new empty project (this can be done with any desired OpenShift user)
# ** It is very important to deploy all the elements in this new unique project,
# because deploying the resources in existing infrastructure could
# potentially alter/delete existing 3scale elements **
export NAMESPACE="operator-test"
oc new-project $NAMESPACE
oc project $NAMESPACE
# Create the 3scale-operator ServiceAccount
oc create -f deploy/service_account.yaml
# Create the roles and role bindings associated to the 3scale-operator
# to be deployed
oc create -f deploy/role.yaml
oc create -f deploy/role_binding.yaml
# Set the desired operator image in the operator YAML. For example,
# the latest available one
sed -i 's|REPLACE_IMAGE|quay.io/3scale/3scale-operator:latest|g' deploy/operator.yaml
# Deploy the 3scale-operator in the created project
oc create -f deploy/operator.yaml
# Verify that the operator is deployed and ready. Execute the
# following command until it shows the Deployment is ready
oc get deployment 3scale-operator
At this point, the 3scale-operator is deployed and ready to accept the
3scale-operator custom resource creation requests that it can process to
perform the provide the functionalities described in the Overview
section.
To see a deploy example of the 3scale-operator, how to deploy example custom
resources to deploy a 3scale API Management solution and 3scale API definitions,
and how to cleanup the operator and the custom resources
refer to the User guide.
Development
Assuming you have already downloaded the 3scale-operator project (see
Getting Started), and your workspace meets prerequisites,
you can easily build and test the operator:
Build operator
Install dependencies
# Activate Go Modules
export GO111MODULE=on
make vendor
Build docker image with the operator installed. Docker image is not pushed to any image repository.
make build IMAGE=quay.io/myorg/3scale-operator VERSION=test
After performing the desired changes in the code, the operator can be executed
locally via the following Makefile rule:
make local
Running locally
Launch the operator on the local machine with the ability to access
a Kubernetes cluster using a kubeconfig file
make local NAMESPACE=operator-test
Testing
Run tests locally deploying image
make e2e-setup NAMESPACE=operator-test
make e2e-run
Run tests locally running operator with go run instead of as an image in the cluster
make e2e-setup NAMESPACE=operator-test
make e2e-local-run
Pushing
make push IMAGE=quay.io/myorg/3scale-operator VERSION=test
Deploy to OpenShift 4 using OLM
To install this operator on OpenShift 4 for end-to-end testing,
create the Operator Source
provided in deploy/olm-catalog/3scale-operatorsource.yaml
to load your operator bundle in OpenShift.
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.
Auto-generated OpenShift templates
As an alternative to using the 3scale-operator we currently are auto-generating
OpenShift templates with some predefined 3scale deployment solution scenarios.
The auto-generated template files generated in this repository are not
supported and might change or be removed at any time without further notice.
The location of the templates in this repository is at:
pkg/3scale/amp/auto-generated-templates
If you want to use supported and stable templates you should go to the
official repository for them
Licenses
It is a requirement that we include a file describing all the licenses used in the product, so that users can examine it.
Run make licenses-check
to check licenses when dependencies change.
Run make licenses.xml
to update licenses file.
When licenses check does not parse correctly licensing information, it will complain. In that case, you can either specify dependency license (recommended) or add exception for that dependency.
Adding license information for a dependency:
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, i.e. manual approval, to a specific 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"
Documentation