@@ -4,6 +4,11 @@ feature](https://open-policy-agent.github.io/gatekeeper/website/docs/externaldat
44with [ Artifact attestations] ( https://github.com/actions/attest ) to determine whether
55the images are valid by verifying its signatures.
66
7+ > [ !IMPORTANT]
8+ > For this to work, OPA Gatekeeper must run with
9+ > ` enableExternalData=true ` , which can be configured during
10+ > installation.
11+
712## Limitations
813
914* mTLS between OPA Gatekeeper and the external data provider is not
@@ -12,129 +17,125 @@ the images are valid by verifying its signatures.
1217
1318## Installation
1419
15- ## Verification
20+ ### Preparation
1621
17- ## Local installation
22+ Before the installation starts, two steps are required to prepare:
1823
19- 1 . Create a [ kind
20- cluster] ( https://kind.sigs.k8s.io/docs/user/quick-start/ ) .
21- 2 . Prepare ` pull-secret ` for private OCI registry (Optional)
24+ 1 . How OPA Gatekeeper authenticates the OPA External Data
25+ Provider. This is done via regular TLS certificates, but they must
26+ be created and made available to the services.
27+ 1 . If private OPI registries are used, the authentication must be
28+ configured.
2229
23- ```
24- $ kubectl create secret docker-registry \
25- ghcr-login-secret \
26- --docker-server=https://ghcr.io \
27- --docker-username=$YOUR_GITHUB_USERNAME \
28- --docker-password=$YOUR_GITHUB_TOKEN \
29- --docker-email=$YOUR_EMAIL
30- ```
30+ #### OCI Authentication
3131
32- 3 . Prepare a pull secret for the OPA external data provider (Optional)
32+ Currently there are two tested authentication methods known to work
33+ with private OCI registries:
3334
34- ```
35- $ kubectl create secret \
36- -n provider-system \
37- docker-registry aa-ghcr-login-secret \
38- --docker-server=https://ghcr.io \
39- --docker-username=$YOUR_GITHUB_USERNAME \
40- --docker-password=$YOUR_GITHUB_TOKEN \
41- --docker-email=$YOUR_EMAIL
42- ```
35+ 1 . Using ` imagePullSecrets `
36+ 2 . Using Managed Identities with Azure Managed Kubernetes Service
37+ (AKS)
4338
44- 4 . Install Gatekeeper and ** enable external data feature**
39+ Although these are the only tested authentication methods, others may
40+ work (Azure using Sevice Principals, GKE and EKS configurations) as
41+ long as the POD/Service Accounts are configured properly.
4542
46- ```
47- # Add the Gatekeeper Helm repository
48- $ helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
49-
50- # Install the latest version of Gatekeeper with the external data feature enabled.
51- $ helm install gatekeeper/gatekeeper \
52- --set enableExternalData=true \
53- --name-template=gatekeeper \
54- --namespace gatekeeper-system \
55- --create-namespace
56- ```
43+ To use ` imagePullSecrets ` , prepare the secret in the namespace used by
44+ the Artifact Attestations OPA Provider. The default name is
45+ ` aa-login-secret ` but can be changed if needed, just make sure to
46+ update the value in ` values.yaml ` before installing.
5747
58- 5 . Generate server TLS for the external data provider
48+ To use Azure Managed Identities, first configure the Managed Identity
49+ with the required permission (ACR Pull against the relevant
50+ registries), then [ configure a federated
51+ credential] ( https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-config-app-trust-managed-identity?tabs=microsoft-entra-admin-center#configure-a-federated-identity-credential-on-an-existing-application )
52+ against the K8s cluster.
5953
60- ```
61- $ ./scripts/gen_certs.sh
62- ```
54+ To enable the use of Azure Managed Identities, you must provide the
55+ Managed Identity's Client ID: ` --set azureClientId=${AZURE_CLIENT_ID} `
56+ during helm install.
6357
64- 6 . Build and load the docker image
58+ #### TLS certificates
6559
66- ```
67- $ make docker
68- $ make kind-load-image
69- ```
60+ > [ !NOTE]
61+ > Tested version of OPA Gatekeeper up to version 3.18.2 only supports
62+ > RSA keys for the TLS certificates.
63+
64+ OPA Gatekeeper relies on TLS authentication when communicating with
65+ external data providers. There is a provided
66+ [ script] ( scripts/gen_certs.sh ) to generate a self signed CA and TLS
67+ certificate. The certificate can be created via other means, as long
68+ as the private key can be mounted as a secret to the Artifact
69+ Attestations OPA Provider POD.
70+
71+ When installing the Artifacts Attestations OPA Provider, the CA
72+ certificate bundle must be provided to configure the root of trust.
7073
71- 7 . Install the data provider
74+ The secret containing the TLS certificate and private key can be
75+ automatically created, or created separately from the helm
76+ installation. The secret must have the name ` provider-tls-cert ` .
7277
73- To automatically provision the server tls certificate/key secret
78+ ### Install via helm
79+
80+ #### Using ` imagePullSecrets `
7481
7582```
7683$ helm install artifact-attestations-opa-provider charts/artifact-attestations-opa-provider \
7784 --set provider.tls.caBundle="$(cat certs/ca.crt | base64 | tr -d '\n\r')" \
7885 --set serverCert="$(cat certs/tls.crt | base64 | tr -d '\n\r')" \
7986 --set serverKey="$(cat certs/tls.key | base64 | tr -d '\n\r')" \
87+ --set imagePullSecrets=<name-of-your-secret> \
8088 --namespace provider-system \
8189 --create-namespace
8290```
8391
84- or if the secret is already created
92+ #### Using Azure Managed Identity
8593
8694```
8795$ helm install artifact-attestations-opa-provider charts/artifact-attestations-opa-provider \
8896 --set provider.tls.caBundle="$(cat certs/ca.crt | base64 | tr -d '\n\r')" \
89- --set serverCert="" \
97+ --set serverCert="$(cat certs/tls.crt | base64 | tr -d '\n\r')" \
98+ --set serverKey="$(cat certs/tls.key | base64 | tr -d '\n\r')" \
99+ --set azureClientId=${AZURE_CLIENT_ID} \
90100 --namespace provider-system \
91101 --create-namespace
92102```
93103
94- 8 . Install constraint template and constraint.
95-
96- From repo:
97-
98- ```
99- $ kubectl apply -f validation/from-repo-constraint-template.yml
100- $ kubectl apply -f validation/from-repo-constraint.yml
101- ```
102-
103- or from org:
104-
105- ```
106- $ kubectl apply -f validation/from-org-constraint-template.yml
107- $ kubectl apply -f validation/from-org-constraint.yml
108- ```
109-
110- or from org with signer (reusable workflow):
104+ #### Using Azure Managed Identity and an existing TLS secret
111105
112106```
113- $ kubectl apply -f validation/from-org-with-signer-constraint-template.yml
114- $ kubectl apply -f validation/from-org-with-signer-constraint.yml
107+ $ helm install artifact-attestations-opa-provider charts/artifact-attestations-opa-provider \
108+ --set provider.tls.caBundle="$(cat certs/ca.crt | base64 | tr -d '\n\r')" \
109+ --set serverCert="" \
110+ --set azureClientId=${AZURE_CLIENT_ID} \
111+ --namespace provider-system \
112+ --create-namespace
115113```
116114
117- 9 . Test with an image from Tina's repository (PGI Sigstore)
115+ ## Verification
118116
119- ```
120- $ kubectl run nginx --image=ghcr.io/tinaheidinger/test-container:latest --dry-run=server -ojson
121- ```
117+ Three examples are provided that can be used as references when
118+ building out the policy.
122119
123- 10 . Test with image from Fredrik's repository (private package, GitHub
124- Sigstore)
120+ The policies are regular OPA Gatekeeper Constraints, where the
121+ enforcement action can be set, and the targeted/ignored resources.
125122
126- ```
127- $ kubectl run nginx --image=ghcr.io/kommendorkapten/ghademo:latest --dry-run=server -ojson
128- ```
123+ When writing the policy using the provided examples, the organization
124+ should be the name of the GitHub org, like ` octo-org ` , and the
125+ repository must include the org name like ` octo-org/octo-repo ` .
129126
130- 11 . Test with image from Fredrik's repository (private package, GitHub
131- Sigstore) using a reusable workflow
127+ The following three examples are provided:
132128
133- ```
134- $ kubectl run nginx --image=ghcr.io/kommendorkapten/ghademo:reusable --dry-run=server -ojson
135- ```
129+ 1 . [ Verify image] ( validation/from-org-constraint-template.yaml ) is
130+ built from a list of provided organizations.
131+ 1 . [ Verify image] ( validation/from-repo-constraint-template.yaml ) is
132+ built from a list of provided repositories.
133+ 1 . [ Verify
134+ image] ( validation/from-org-with-signer-constraint-template.yaml ) is
135+ originating from a list of organizations, and built with a reusable
136+ workflow from a list of provided repositories.
136137
137- ### Cleaning up
138+ ## Uninstall
138139
139140```
140141$ kubectl delete -f validation
0 commit comments