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.
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.
- operator-sdk version v0.8.0.
- 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.
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.
# 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:
Launch the operator on the local machine with the ability to access a Kubernetes cluster using a kubeconfig file
make local NAMESPACE=operator-test
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
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
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:
If you want to use supported and stable templates you should go to the official repository for them
It is a requirement that we include a file describing all the licenses used in the product, so that users can examine it.
make licenses-check to check licenses when dependencies change.
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"
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"
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"