Developer's Guide
- Technology stack for developers
- Workflow
- Check the issues
- Clone the repo and setup the local environment
- Make your changes
- Run the tests
- Try locally
- Sign your commits
- Logging policy
- Additional resources
- Reach out
Technology stack for developers
Minimum requirements to contribute to Authorino are: - Golang v1.19+ - Docker
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]https://cs.opensource.google/go/x/perf): 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:
- jq
- yq
- gnu-sed
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:
Download the Golang dependencies:
For additional automation provided, check:
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:
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
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
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](https://github.com/kuadrant/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:Keycloak
Authorino examples include a bundle of [Keycloak](https://www.keycloak.org) preloaded with the following realm setup:- Admin console: http://localhost:8080/auth/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: Forward local requests to the instance of Keycloak running in the cluster:
Dex
Authorino examples include a bundle of [Dex](https://dexidp.io) 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: Forward local requests to the instance of Dex running in the cluster:
a12n-server
Authorino examples include a bundle of [**a12n-server**](https://github.com/curveball/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: Forward local requests to the instance of a12n-server running in the cluster:
Re-build and rollout latest
Re-build and rollout latest Authorino image:
If you made changes to the CRD between iterations, re-install by running:
Clean-up
The following command deletes the entire Kubernetes cluster started with Kind:
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.