Skip to content

Latest commit

 

History

History
258 lines (178 loc) · 10 KB

contributing.md

File metadata and controls

258 lines (178 loc) · 10 KB
Raw

Developer's Guide

Technology stack for developers

Minimum requirements to contribute to Authorino are:

Authorino's code was originally bundled using the Operator SDK (v1.9.0).

The following tools can be installed as part of the development workflow:

  • Installed with go install to the $PROJECT_DIR/bin directory:

    • controller-gen: for building custom types and manifests
    • Kustomize: for assembling flavoured manifests and installing/deploying
    • setup-envtest: for running the tests – extra tools installed to ./testbin
    • benchstat: for human-friendly test benchmark reports
    • mockgen: to generate mocks for tests – e.g. ./bin/mockgen -source=pkg/auth/auth.go -destination=pkg/auth/mocks/mock_auth.go
    • Kind: for deploying a containerized Kubernetes cluster for integration testing purposes

  • Other recommended tools to have installed:

Workflow

Development workflow

Check the issues

Start by checking the list of issues in GitHub.

In case you want to contribute with an idea for enhancement, a bug fix, or question, please make sure to describe the issue so we can start a conversation together and help you find the best way to get your contribution merged.

Clone the repo and setup the local environment

Fork/clone the repo:

git clone [email protected]:kuadrant/authorino.git && cd authorino

Download the Golang dependencies:

make vendor

For additional automation provided, check:

make help

Make your changes

Good changes...

  • follow the Golang conventions
  • have proper test coverage
  • address corresponding updates to the docs
  • help us fix wherever we failed to do the above 😜

Run the tests

To run the tests:

make test

Try locally

Build, deploy and try Authorino in a local cluster

The following command will:

  • Start a local Kubernetes cluster (using Kind)
  • Install cert-manager in the cluster
  • Install the Authorino Operator and Authorino CRDs
  • Build an image of Authorino based on the current branch
  • Push the freshly built image to the cluster's registry
  • Generate TLS certificates for the Authorino service
  • Deploy an instance of Authorino
  • Deploy the example application Talker API, a simple HTTP API that echoes back whatever it gets in the request
  • Setup Envoy for proxying to the Talker API and using Authorino for external authorization
make local-setup

You will be prompted to edit the Authorino custom resource.

The main workload composed of Authorino instance and user apps (Envoy, Talker API) will be deployed to the default Kubernetes namespace.

Once the deployment is ready, you can forward the requests on port 8000 to the Envoy service

kubectl port-forward deployment/envoy 8000:8000 &
Pro tips
  1. Change the default workload namespace by supplying the NAMESPACE argument to your make local-setup and other deployment, apps and local cluster related targets. If the namespace does not exist, it will be created.
  2. Switch to TLS disabled by default when deploying locally by supplying TLS_ENABLED=0 to your make local-setup and make deploy commands. E.g. make local-setup TLS_ENABLED=0.
  3. Skip being prompted to edit the Authorino CR and default to an Authorino deployment with TLS enabled, debug/development log level/mode, and standard name 'authorino', by supplying FF=1 to your make local-setup and make deploy commands. E.g. make local-setup FF=1
  4. Supply DEPLOY_IDPS=1 to make local-setup and make user-apps to deploy Keycloak and Dex to the cluster. DEPLOY_KEYCLOAK and DEPLOY_DEX are also available. Read more about additional tools for specific use cases in the section below.
  5. Saving the ID of the process (PID) of the port-forward command spawned in the background can be useful to later kill and restart the process. E.g. kubectl port-forward deployment/envoy 8000:8000 &;PID=$!; then kill $PID.

Additional tools (for specific use-cases)

Limitador

To deploy Limitador – pre-configured in Envoy for rate-limiting the Talker API to 5 hits per minute per user_id when available in the cluster workload –, run:

kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/limitador/limitador-deploy.yaml
Keycloak

Authorino examples include a bundle of Keycloak preloaded with the following realm setup:

  • Admin console: http://localhost:8080/admin (admin/p)
  • Preloaded realm: kuadrant
  • Preloaded clients:
    • demo: to which API consumers delegate access and therefore the one which access tokens are issued to
    • authorino: used by Authorino to fetch additional user info with client_credentials grant type
    • talker-api: used by Authorino to fetch UMA-protected resource data associated with the Talker API
  • Preloaded resources:
    • /hello
    • /greetings/1 (owned by user john)
    • /greetings/2 (owned by user jane)
    • /goodbye
  • Realm roles:
    • member (default to all users)
    • admin
  • Preloaded users:
    • john/p (member)
    • jane/p (admin)
    • peter/p (member, email not verified)

To deploy, run:

kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/keycloak/keycloak-deploy.yaml

Forward local requests to the instance of Keycloak running in the cluster:

kubectl port-forward deployment/keycloak 8080:8080 &
Dex

Authorino examples include a bundle of Dex preloaded with the following setup:

  • Preloaded clients:
    • demo: to which API consumers delegate access and therefore the one which access tokens are issued to (Client secret: aaf88e0e-d41d-4325-a068-57c4b0d61d8e)
  • Preloaded users:
    • marta@localhost/password

To deploy, run:

kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/dex/dex-deploy.yaml

Forward local requests to the instance of Dex running in the cluster:

kubectl port-forward deployment/dex 5556:5556 &
a12n-server

Authorino examples include a bundle of a12n-server and corresponding MySQL database, preloaded with the following setup:

  • Admin console: http://a12n-server:8531 (admin/123456)
  • Preloaded clients:
    • service-account-1: to obtain access tokens via client_credentials OAuth2 grant type, to consume the Talker API (Client secret: DbgXROi3uhWYCxNUq_U1ZXjGfLHOIM8X3C2bJLpeEdE); includes metadata privilege: { "talker-api": ["read"] } that can be used to write authorization policies
    • talker-api: to authenticate to the token introspect endpoint (Client secret: V6g-2Eq2ALB1_WHAswzoeZofJ_e86RI4tdjClDDDb4g)

To deploy, run:

kubectl apply -f https://raw.githubusercontent.com/kuadrant/authorino-examples/main/a12n-server/a12n-server-deploy.yaml

Forward local requests to the instance of a12n-server running in the cluster:

kubectl port-forward deployment/a12n-server 8531:8531 &

Re-build and rollout latest

Re-build and rollout latest Authorino image:

make local-rollout

If you made changes to the CRD between iterations, re-install by running:

make install

Clean-up

The following command deletes the entire Kubernetes cluster started with Kind:

make local-cleanup

Sign your commits

All commits to be accepted to Authorino's code are required to be signed. Refer to this page about signing your commits.

Logging policy

A few guidelines for adding logging messages in your code:

  1. Make sure you understand Authorino's Logging architecture and policy regarding log levels, log modes, tracing IDs, etc.
  2. Respect controller-runtime's Logging Guidelines.
  3. Do not add sensitive data to your info log messages; instead, redact all sensitive data in your log messages or use debug log level by mutating the logger with V(1) before outputting the message.

Additional resources

Here in the repo:

Other repos:

Reach out

#kuadrant channel on kubernetes.slack.com.