-
Notifications
You must be signed in to change notification settings - Fork 95
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add docs on development and releasing (#143)
Signed-off-by: Ernest Wong <[email protected]>
- Loading branch information
Ernest Wong
authored
Aug 11, 2021
1 parent
a611704
commit c04c282
Showing
10 changed files
with
270 additions
and
9 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,238 @@ | ||
| # Development | ||
|
|
||
| <!-- toc --> | ||
|
|
||
| ## Setting up | ||
|
|
||
| ### Base requirements | ||
|
|
||
| 1. Prerequisites from [quickstart](https://azure.github.io/aad-pod-managed-identity/quick-start.html#prerequisites) | ||
| 2. Install [go](https://golang.org/dl/) | ||
| - Get the latest patch version for go 1.16. | ||
| 3. Install [jq](https://stedolan.github.io/jq/) | ||
| - `brew install jq` on macOS. | ||
| - `chocolatey install jq` on Windows. | ||
| - `sudo apt install jq` on Ubuntu Linux. | ||
| 4. Install make. | ||
|
|
||
| ### Clone the repository | ||
|
|
||
| ```bash | ||
| git clone https://github.com/Azure/aad-pod-managed-identity.git $(go env GOPATH)/src/github.com/Azure/aad-pod-managed-identity | ||
| ``` | ||
|
|
||
| ## Create a test cluster | ||
|
|
||
| ### Generate a custom public/private key pair | ||
|
|
||
| > Skip this step if you are planning to bring your own keys. | ||
| ```bash | ||
| openssl genrsa -out sa.key 2048 | ||
| openssl rsa -in sa.key -pubout -out sa.pub | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary>Output</summary> | ||
|
|
||
| ```bash | ||
| Generating RSA private key, 2048 bit long modulus | ||
| ..............+++ | ||
| ......+++ | ||
| e is 65537 (0x10001) | ||
| writing RSA key | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| ### Setup the OIDC discovery document and JWKS | ||
|
|
||
| > Skip this step if you already set up the OIDC discovery document and JWKS. | ||
| Azure blob storage will be used to host the OIDC discovery document and JWKS. However, you can host them in anywhere, as long as they are publicly available. | ||
|
|
||
| ```bash | ||
| export AZURE_STORAGE_ACCOUNT="pmi$(openssl rand -hex 4)" | ||
| export AZURE_STORAGE_CONTAINER="oidc-test" | ||
| az storage account create --resource-group "${RESOURCE_GROUP}" --name "${AZURE_STORAGE_ACCOUNT}" | ||
| az storage container create --name "${AZURE_STORAGE_CONTAINER}" --public-access container | ||
| ``` | ||
|
|
||
| Generate and upload the OIDC discovery document: | ||
|
|
||
| ```bash | ||
| cat <<EOF > openid-configuration.json | ||
| { | ||
| "issuer": "https://${AZURE_STORAGE_ACCOUNT}.blob.core.windows.net/${AZURE_STORAGE_CONTAINER}/", | ||
| "authorization_endpoint": "https://${AZURE_STORAGE_ACCOUNT}.blob.core.windows.net/${AZURE_STORAGE_CONTAINER}/connect/authorize", | ||
| "jwks_uri": "https://${AZURE_STORAGE_ACCOUNT}.blob.core.windows.net/${AZURE_STORAGE_CONTAINER}/openid/v1/jwks", | ||
| "response_types_supported": [ | ||
| "id_token" | ||
| ], | ||
| "subject_types_supported": [ | ||
| "public" | ||
| ], | ||
| "id_token_signing_alg_values_supported": [ | ||
| "RS256" | ||
| ] | ||
| } | ||
| EOF | ||
| az storage blob upload \ | ||
| --container-name "${AZURE_STORAGE_CONTAINER}" \ | ||
| --file openid-configuration.json \ | ||
| --name .well-known/openid-configuration | ||
| ``` | ||
|
|
||
| Generate and upload the JWKS: | ||
|
|
||
| ```bash | ||
| pushd hack/generate-jwks | ||
| go run main.go --public-keys ../../sa.pub | jq > jwks.json | ||
| az storage blob upload \ | ||
| --container-name "${AZURE_STORAGE_CONTAINER}" \ | ||
| --file jwks.json \ | ||
| --name openid/v1/jwks | ||
| popd | ||
| ``` | ||
|
|
||
| Verify that the OIDC discovery document is publicly accessible: | ||
|
|
||
| ```bash | ||
| curl -s "https://${AZURE_STORAGE_ACCOUNT}.blob.core.windows.net/${AZURE_STORAGE_CONTAINER}/.well-known/openid-configuration" | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary>Output</summary> | ||
|
|
||
| ```json | ||
| { | ||
| "issuer": "https://<REDACTED>.blob.core.windows.net/oidc-test/", | ||
| "authorization_endpoint": "https://<REDACTED>.blob.core.windows.net/oidc-test/connect/authorize", | ||
| "jwks_uri": "https://<REDACTED>.blob.core.windows.net/oidc-test/openid/v1/jwks", | ||
| "response_types_supported": [ | ||
| "id_token" | ||
| ], | ||
| "subject_types_supported": [ | ||
| "public" | ||
| ], | ||
| "id_token_signing_alg_values_supported": [ | ||
| "RS256" | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| ### Create a kind cluster | ||
|
|
||
|
|
||
| Export the following environment variables: | ||
|
|
||
| ```bash | ||
| export SERVICE_ACCOUNT_ISSUER="https://${AZURE_STORAGE_ACCOUNT}.blob.core.windows.net/${AZURE_STORAGE_CONTAINER}/" | ||
| export SERVICE_ACCOUNT_KEY_FILE="$(pwd)/sa.pub" | ||
| export SERVICE_ACCOUNT_SIGNING_KEY_FILE="$(pwd)/sa.key" | ||
| ``` | ||
|
|
||
| Create a kind cluster with one control plane node and customize various service account-related flags for the API server: | ||
|
|
||
| > The minimum supported Kubernetes version for the webhook is v1.18.0, however, we recommend using Kubernetes version v1.20.0+. | ||
| ```bash | ||
| cat <<EOF | kind create cluster --name aad-pod-managed-identity --image kindest/node:v1.21.1 --config=- | ||
| kind: Cluster | ||
| apiVersion: kind.x-k8s.io/v1alpha4 | ||
| nodes: | ||
| - role: control-plane | ||
| extraMounts: | ||
| - hostPath: ${SERVICE_ACCOUNT_KEY_FILE} | ||
| containerPath: /etc/kubernetes/pki/sa.pub | ||
| - hostPath: ${SERVICE_ACCOUNT_SIGNING_KEY_FILE} | ||
| containerPath: /etc/kubernetes/pki/sa.key | ||
| kubeadmConfigPatches: | ||
| - | | ||
| kind: ClusterConfiguration | ||
| apiServer: | ||
| extraArgs: | ||
| service-account-issuer: ${SERVICE_ACCOUNT_ISSUER} | ||
| service-account-key-file: /etc/kubernetes/pki/sa.pub | ||
| service-account-signing-key-file: /etc/kubernetes/pki/sa.key | ||
| EOF | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary>Output</summary> | ||
|
|
||
| ```bash | ||
| Creating cluster "aad-pod-managed-identity" ... | ||
| • Ensuring node image (kindest/node:v1.21.1) 🖼 ... | ||
| ✓ Ensuring node image (kindest/node:v1.21.1) 🖼 | ||
| • Preparing nodes 📦 ... | ||
| ✓ Preparing nodes 📦 | ||
| • Writing configuration 📜 ... | ||
| ✓ Writing configuration 📜 | ||
| • Starting control-plane 🕹️ ... | ||
| ✓ Starting control-plane 🕹️ | ||
| • Installing CNI 🔌 ... | ||
| ✓ Installing CNI 🔌 | ||
| • Installing StorageClass 💾 ... | ||
| ✓ Installing StorageClass 💾 | ||
| Set kubectl context to "kind-aad-pod-managed-identity" | ||
| You can now use your cluster with: | ||
|
|
||
| kubectl cluster-info --context kind-aad-pod-managed-identity | ||
|
|
||
| Have a question, bug, or feature request? Let us know! https://kind.sigs.k8s.io/#community 🙂 | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| Run the following command to verify that the kind cluster is online: | ||
|
|
||
| ```bash | ||
| kubectl get nodes | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary>Output</summary> | ||
|
|
||
| ```bash | ||
| NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME | ||
| aad-pod-managed-identity-control-plane Ready control-plane,master 2m28s v1.21.1 172.18.0.2 <none> Ubuntu 21.04 5.4.0-1047-azure containerd://1.5.2 | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
|
|
||
| ## Build and deploy the webhook | ||
|
|
||
| ```bash | ||
| export REGISTRY=<YourPublicRegistry> | ||
| export IMAGE_VERSION="$(git describe --tags --always)" | ||
| export AZURE_TENANT_ID="..." | ||
| make docker-build-webhook deploy | ||
| ``` | ||
|
|
||
| ## Unit Test | ||
|
|
||
| ```bash | ||
| make test | ||
| ``` | ||
|
|
||
| ## E2E Test | ||
|
|
||
| ```bash | ||
| make test-e2e-run | ||
| ``` | ||
|
|
||
| Optional settings are: | ||
|
|
||
| | Environment variables | Description | Default | | ||
| |-----------------------|--------------------------------------------------------------------|------------------------| | ||
| | `GINKGO_FOCUS` | Allow you to focus on a subset of specs using regex. | | | ||
| | `GINKGO_SKIP` | Allow you to skip a subset of specs using regex. | | | ||
| | `GINKGO_NODES` | The number of ginkgo workers to run the specs. | `3` | | ||
| | `GINKGO_NO_COLOR` | True if you want colorized output. | `false` | | ||
| | `GINKGO_TIMEOUT` | The test suite timeout duration. | `5m` | | ||
| | `KUBECONFIG` | The cluster KUBECONFIG you want to run the e2e test against. | `${HOME}/.kube/config` | | ||
| | `E2E_EXTRA_ARGS` | Allow you to insert extra arguments when executing the test suite. | | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| # Releasing | ||
|
|
||
| <!-- toc --> | ||
|
|
||
| We use GitHub Actions to automate our release process. | ||
|
|
||
| ## 1. Create a release pull request | ||
|
|
||
|  | ||
|
|
||
| ## 2. Review and approve the release pull request | ||
|
|
||
|  | ||
|
|
||
| ## 3. Verify that the create_tag action is triggered after the release pull request is merged | ||
|
|
||
|  | ||
|
|
||
| ## 4. Verify that the tag is successfully created | ||
|
|
||
|  |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters