--- component: provenance-governor version: "1.7" slug: provenance-governor/setup-deploy canonical_url: "https://docs.gradle.com/develocity/provenance-governor/1.7/setup-deploy/" title: "Deployment" description: "Deployment instructions for Develocity Provenance Governor." keywords: - "Kubernetes" - "Helm chart" - "installation" - "configuration" status: current --- # Deployment Develocity Provenance Governor is provided as a container image that runs on a Kubernetes cluster. Make sure you have the prerequisites detailed in [Prerequisites](https://docs.gradle.com/develocity/provenance-governor/1.7/setup-prerequisites/) before proceeding. > [!TIP] > Looking for Docker deployment without Kubernetes? See the Docker Deployment Guide. ## Audience This guide is written for a Platform / Infrastructure Engineer. It assumes: * Basic familiarity with Kubernetes (namespaces, secrets, configmaps, deployments, ingress) * Ability to obtain a Develocity license file (`develocity.license`) * (Optional) Ability to obtain access tokens/keys for Develocity and Artifactory instances * Access to a DNS domain (optional, for public HTTPS ingress) ## Quickstart Want to get started quickly with a local k3d cluster and basic HTTP ingress? See the [Quickstart Guide](https://docs.gradle.com/develocity/provenance-governor/1.7/quickstart/) for condensed setup instructions. The quickstart will guide you through: * Creating a local k3d cluster * Deploying Develocity Provenance Governor with basic HTTP ingress * Verifying the deployment After completing the quickstart, return to the sections below to configure additional features like authentication, integrations, and policies. ## Deployment Flow Overview The recommended order is: 1. [Choose / create a Kubernetes cluster](#select-kubernetes-distribution) (local k3d or existing) 2. [Create namespace + required secrets](#prepare-kubernetes-namespace-required-secrets) (registry + license) 3. [Configure Ingress](#ingress-optional) (HTTP, then HTTPS + cert-manager) - Optional 4. [Deploy the core workload](#deploy-core-components) (ServiceAccount, Services, Deployment, NetworkPolicy) 5. [Verify rollout & logs](#verification-next-steps) 6. [Create placeholder Secrets/ConfigMaps](#create-placeholders-dynamic-config) for dynamic configuration (`secrets`, `properties`, `policies`) 7. [Add integrations](#develocity-deploy) ([Develocity instances](#develocity-deploy), [Artifactory instances](#artifactory-deploy)) 8. [Add signing keys](#signing-keys-deploy) 9. [Enable authentication](#authentication-deploy) (Basic and/or OIDC) 10. [Define policies](#policies-optional) (AccessControl manifests) 11. Roll out config changes as needed 12. [Troubleshoot rollout issues](#troubleshooting-deployment-rollouts) Estimated setup time: * **Local k3d (Quickstart)**: 15-30 minutes * **Production setup with all integrations**: 2-4 hours (depending on external service coordination and certificate setup) ## Select Kubernetes Distribution Before proceeding ensure access to a Kubernetes cluster has been provided, otherwise a local k3d cluster is also supported. ### k3d **Install k3d:** ``` brew install k3d ``` **Create k3d cluster (port 80 exposed for ingress):** ``` k3d cluster create --port "80:80@loadbalancer" ``` ## Prepare the Kubernetes Namespace and Required Secrets You must create a Kubernetes namespace and the secrets needed for the application to start. ### Create Kubernetes Namespace **Namespace that the Develocity Provenance Governor will be deployed to.:** ``` kubectl create namespace develocity-provenance-governor ``` ### Docker Registry Secret (Required) Authenticate to `registry.gradle.com` to pull the product image. ```bash kubectl create secret docker-registry registry-secret \ --namespace develocity-provenance-governor \ --docker-server=https://registry.gradle.com \ --docker-username=user \ --docker-password=$(cat ./develocity.license) ``` ### Develocity License Secret (Required) A Develocity license is required for the deployment to be successful. ```shell kubectl create secret generic license \ --namespace develocity-provenance-governor \ --from-file=develocity.license=./develocity.license ``` ## Ingress (Optional) No default ingress is provided. Choose what aligns with organizational standards. Below examples cover: * Local development (nip.io hostname) * HTTPS with cert-manager & Let’s Encrypt **Create Ingress Manifest:** ``` kubectl --namespace develocity-provenance-governor apply -f - < ### Ingress with cert-manager Alternative, ingress manifest using cert-manager, nginx, and signed certificate from Let’s Encrypt. The ingress resource, can be used to expose the api service outside the cluster. Modify the provided manifest to reflect the domain that you control paying close attention to `tls[0].hosts[0]` and `rules[0].host`. ```shell kubectl --namespace develocity-provenance-governor apply -f - < [!NOTE] > This will create a certificate issuer using the Production Instance of Let’s Encrypt. Edit accordingly based on desired certificate issuer implementation. If using Let’s Encrypt, ensure the ingress is publicly accessible and can handle a http01 challenge provider request to complete certificate issuance. Also, be sure to update the email address. **Verify the Issuer:** ``` kubectl describe issuer lets-encrypt \ --namespace develocity-provenance-governor ``` Detailed issuer information should be returned along with `Status.Status: True` and `Status.Type: Ready`. Edit the `https` ingress resource to use the `lets-encrypt` issuer instead of the self signed certificate issuer. **Edit ingress resource:** ``` kubectl edit ingress https \ --namespace develocity-provenance-governor ``` **Add cert-manager.io/issuer: lets-encrypt to annotations::** ``` metadata: annotations: cert-manager.io/issuer: lets-encrypt ``` **Verify Certificate Issued:** ``` $ kubectl get certificate \ --namespace develocity-provenance-governor NAME READY SECRET AGE https-api-tls True https-api-tls 2m31s ``` Verify Https Endpoint $ curl [https://provenance-governor.example.com](https://provenance-governor.example.com) -i HTTP/2 401 …​ In this example, the request to `[https://provenance-governor.example.com](https://provenance-governor.example.com)` returns a `401 Unauthorized` status code because no credentials were provided. This confirms that the Ingress is correctly routing traffic to the service and that the service is up and running. To verify the service health: ```bash curl https://provenance-governor.example.com/readyz -i ``` No SSL negotiation exceptions should be thrown and a 401 should be returned. ## Deploy Core Components Apply the workload manifests. (See Quickstart) Download the [manifest.yaml](https://docs.gradle.com/develocity/provenance-governor/1.7/_attachments/manifest.yaml) file. ```shell kubectl --namespace develocity-provenance-governor apply -f manifest.yaml ``` **Verify Rollout:** ``` kubectl rollout status deployment/api \ --timeout=90s \ --namespace develocity-provenance-governor ``` Expected output: `deployment "api" successfully rolled out`. If rollout fails: * Verify `registry-secret` credentials and image digest/tag * Verify `license` secret presence and correct file content **Verify Logs:** ``` kubectl logs deployment/api \ --namespace develocity-provenance-governor | grep -i license ``` **Sample lines:** ``` Develocity license enabled, with license [...] Started ProvenanceGovernor in ... ``` ## Create Placeholders for Dynamic Configuration (Optional but Recommended) The Deployment mounts (optionally) these resources:
ResourceKindPurposeRequiredMounted Path
licenseSecretDevelocity product licenseYes/workspace/config/license
secretsSecretSensitive values (access tokens, private keys)No/workspace/config/secrets
propertiesConfigMapNon-sensitive configuration (URIs, public keys)No/workspace/config/properties
policiesConfigMapPolicy manifestsNo/workspace/config/policies
Create empty resources to prepare for configuration: ```shell kubectl create secret generic secrets --namespace develocity-provenance-governor || true kubectl create configmap properties --namespace develocity-provenance-governor || true kubectl create configmap policies --namespace develocity-provenance-governor || true ``` ## Configure Develocity Instances (Optional) Use one or more Develocity instances as attestation data sources. Key patterns: * Secret: `develocity.instances..access-key` * ConfigMap: `develocity.instances..uri` `` must be alphanumeric plus dashes or underscores. **Edit Secret:** ``` kubectl edit secret secrets --namespace develocity-provenance-governor ``` Add access key (use `stringData:` when adding new values): ```yaml stringData: develocity.instances.MY_INSTANCE.access-key: DEVELOCITY_ACCESS_KEY ``` **Edit ConfigMap:** ``` kubectl edit configmap properties --namespace develocity-provenance-governor ``` Add URI: ```yaml data: develocity.instances.MY_INSTANCE.uri: https://develocity.example.com ``` Rollout & Verify: ```shell kubectl rollout restart deployment/api --namespace develocity-provenance-governor kubectl rollout status deployment/api --namespace develocity-provenance-governor --timeout=90s kubectl logs deployment/api --namespace develocity-provenance-governor | grep -i "Develocity support enabled" ``` Expected log snippet: ```text Develocity support enabled, for instance [MY_INSTANCE:https://develocity.example.com] ``` Troubleshooting: Repeated `Retrying [n/10] request …​` indicates connectivity or credential issues. ## Configure Artifactory Instances (Optional) Used to publish attestation data. Key patterns: * Secret: `artifactory.instances..access-token` (token preferred over legacy key) * ConfigMap: `artifactory.instances..uri` **Edit Secret:** ``` kubectl edit secret secrets --namespace develocity-provenance-governor ``` Add token: ```yaml stringData: artifactory.instances.MY_ARTIFACTORY.access-token: ARTIFACTORY_ACCESS_TOKEN ``` **Edit ConfigMap:** ``` kubectl edit configmap properties --namespace develocity-provenance-governor ``` Add URI: ```yaml data: artifactory.instances.MY_ARTIFACTORY.uri: https://artifactory.example.com ``` Rollout & Verify: ```shell kubectl rollout restart deployment/api --namespace develocity-provenance-governor kubectl rollout status deployment/api --namespace develocity-provenance-governor --timeout=90s kubectl logs deployment/api --namespace develocity-provenance-governor | grep -i "Artifactory support enabled" ``` Expected log snippet: ```text Artifactory support enabled, for instance [MY_ARTIFACTORY:https://artifactory.example.com] ``` ## Configure Signing Keys (Optional but Recommended for Attestations) Attestations are wrapped in a [Dead Simple Signing Envelope (DSSE)](https://github.com/secure-systems-lab/dsse/blob/master/background.md) signed by a key pair. Required key property patterns: * Secret (private key, base64 PEM): `signing.key..private-pem` * ConfigMap (public key PEM block): `signing.key..public-pem` Choose a naming convention like `_YYYY-MM-DD` for rotation clarity. ### Create Ed25519 Key Pair Recommended (128-bit security, small key sizes/signatures). ```shell openssl genpkey \ -algorithm Ed25519 \ -out private-key.pem ``` **Use OpenSSL to create a Public Key based on the Private Key:** ``` openssl pkey \ -in private-key.pem \ -pubout \ -out public-key.pem ``` **Edit Secrets:** ``` kubectl edit secret secrets \ --namespace develocity-provenance-governor ``` Base64 and add private key (Secret): ```shell base64 -i private-key.pem | pbcopy kubectl edit secret secrets --namespace develocity-provenance-governor ``` Paste under `data:` (Kubernetes will not modify pasted base64): ```yaml data: signing.key.FRIENDLY_KEY_NAME.private-pem: ``` **Add public key (ConfigMap)::** ``` cat public-key.pem | sed 's/^/ /' | pbcopy kubectl edit configmap properties --namespace develocity-provenance-governor ``` Paste under `data:`: ```yaml data: # PASTE THE PUBLIC KEY BLOCK HERE FROM CLIPBOARD signing.key.FRIENDLY_KEY_NAME.public-pem: | -----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY----- ``` Rollout & Verify: ```shell kubectl rollout restart deployment/api --namespace develocity-provenance-governor kubectl logs deployment/api --namespace develocity-provenance-governor | grep -i "Signature support enabled" ``` Expected log: ```text Signature support enabled, for key pair [name:FRIENDLY_KEY_NAME:keyid:XXXXXX:signing-algorithm:ed25519] ``` Key ID is a 6-character abbreviation of the SHA-256 digest of the public key. ### Other Supported Algorithms Elliptic Curve (ECDSA) and RSA are also supported. Substitute commands below; follow the same secret/configmap procedure. #### Elliptic Curve (prime256v1) ```shell openssl ecparam -name prime256v1 -genkey -noout -out ec_private.key openssl pkcs8 -topk8 -inform PEM -in ec_private.key -outform PEM -nocrypt -out private-key.pem openssl ec -in ec_private.key -pubout -out public-key.pem ``` Expected log algorithm: `SHA256withECDSA`. #### RSA (2048) ```shell openssl genrsa -out private-key.pem 2048 openssl rsa -in private-key.pem -pubout -out public-key.pem ``` Expected log algorithm: `SHA256withRSA`. ## Authentication (Optional) Supported schemes: * [RFC9110 Basic](https://datatracker.ietf.org/doc/html/rfc9110#section-11.1) * [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) + [OAuth 2.0](https://openid.net/specs/openid-connect-core-1_0.html#RFC6749) ### Enable Basic Authentication Add identities under: * Secret key pattern: `basic.identities.` `` is a human-friendly identifier. No default credentials exist. ```shell kubectl edit secret secrets --namespace develocity-provenance-governor ``` **Add a new Basic Identity:** ``` stringData: basic.identities.some-user: '{noop}some-pass' ``` Recommendation: Replace `{noop}` with `{bcrypt}` and supply a bcrypt-hashed password. **Rollout Deployment:** ``` kubectl rollout restart deployment/api \ --namespace develocity-provenance-governor ``` **Verify Basic Authentication Enabled:** ``` kubectl logs deployment/api \ --namespace develocity-provenance-governor | grep -i "Basic Identity support" ``` **Expected Log Line:** ``` Basic Identity support enabled, for identity [some-user] ``` ### Enable OIDC Authentication OIDC Providers are dynamically discovered based on token issuers specified in policies. See the Policies section for examples. ## Policies (Optional) Policies are YAML documents stored inside the `policies` ConfigMap. Each key corresponds to a file-style name ending with `.yaml`. ### Access Control Policies Define who can do what on which resources. `identityMatchingStrategy` supported: * `withBasicIdentity` – must match a key under `basic.identities.` in `secrets` * `withOidc` – relies on issuer discovery; ensure network accessibility `canPerform` supported actions: \* `publish-attestations` - publish DSSE-wrapped attestations to an Attestation Store (S3 or Artifactory) \* `publish-policy-scans` - publish Policy Scan™ results to an Attestation Store `withResources` supported patterns: * `pkg:pkg-type/pkg-namespace/pkg-name@pkg-vesion` - specific Package URL pattern to match or use wildcards: * `pkg:maven/*` - all Maven packages * `pkg:oci/*` - all OCI packages (container images) * `pkg:maven/org.example/**@**` - all Maven packages in `org.example` namespace and any version * `pkg:maven/org.example/acme-app@1.0.0` - specific Maven package * `pkg:oci/image-name@v1*` - specific OCI image with wildcard version * `*:REPLACE_WITH_DV_INSTANCE_NAME/*` - allow to read build scans from the Develocity Instance to source data for attestations. * `*:REPLACE_WITH_ARTIFACTORY_INSTANCE_NAME/*` - allow to publish attestations to the Artifactory instance. Replace `*` with the repository name in Artifactory to restrict access further. * `s3:REPLACE_WITH_S3_INSTANCE_NAME/*` - allow to publish attestations to the S3 instance. * `*:*/*` - allows authenticated identity access to all resources (not recommended for production use) #### Basic Identity Policy Example ```shell kubectl edit configmap policies --namespace develocity-provenance-governor ``` **Add basic-identity-some-user-full-access.yaml policy:** ``` data: basic-identity-some-user-full-access.yaml: | apiVersion: policy.gradle.com/v1 kind: AccessControl metadata: name: basic-identity-some-user-full-access spec: identityMatchingStrategy: withBasicIdentity: - withName: "some-user" canPerform: - publish-attestations - publish-policy-scans withResources: - "*:*/*" ``` #### OIDC Policy Example (GitHub Actions) ```shell kubectl edit configmap policies --namespace develocity-provenance-governor ``` **Add oidc-github-action-full-access.yaml policy:** ``` data: oidc-github-action-full-access.yaml: | apiVersion: policy.gradle.com/v1 kind: AccessControl metadata: name: oidc-github-action-full-access spec: identityMatchingStrategy: withOidc: - fromIssuerUri: https://token.actions.githubusercontent.com withClaims: job_workflow_ref: org/automation-repo/.github/workflows/build-image.yml@* canPerform: - publish-attestations - publish-policy-scans withResources: - "*:*/*" ``` ### Public Key Verification Policy Example ```shell kubectl edit configmap policies --namespace develocity-provenance-governor ``` **Add public-key-verification-policy.yaml policy:** ``` data: public-key-verification-policy.yaml: | apiVersion: policy.gradle.com/v1 kind: TrustedPublicKeys metadata: name: public-keys spec: resultsLabels: [] description: Public keys trusted for attestations. remediation: Update the list of trusted public keys to ensure only verified attestations are accepted. keys: DEPLOYMENT_KEY_2025_10_01: pem: | -----BEGIN PUBLIC KEY----- .... -----END PUBLIC KEY----- ``` Replace `DEPLOYMENT_KEY_2025_10_01` and the PEM block with your actual trusted public keys, for example the ones used to sign attestations. **Rollout Deployment:** ``` kubectl rollout restart deployment/api \ --namespace develocity-provenance-governor kubectl rollout status deployment/api \ --namespace develocity-provenance-governor \ --timeout=90s ``` **Verify Policies Loaded:** ``` kubectl logs deployment/api \ --namespace develocity-provenance-governor | grep -i "Loading Policy Resource from file" ``` **Expected Log Lines:** ``` Loading Policy Resource from file [/workspace/config/policies/public-key-verification-policy.yaml] ``` ## Troubleshooting Deployment Rollouts Common rollout hang: ```text Waiting for deployment "api" rollout to finish: 1 old replicas are pending termination... error: timed out waiting for the condition ``` Inspect pods: ```shell kubectl get pods --namespace develocity-provenance-governor ``` Identify failing pod (e.g., `CrashLoopBackOff`) and fetch logs: ```shell kubectl logs api- --namespace develocity-provenance-governor ``` Example configuration error: ```text *************************** APPLICATION FAILED TO START *************************** Failed to bind properties under 'artifactory.instances.INSTANCE_NAME_GOES_HERE' ... Reason: java.lang.IllegalArgumentException: uri must not be null ``` Remediation: * Missing URI – edit `properties` ConfigMap key `artifactory.instances..uri` * Missing token – edit `secrets` key `artifactory.instances..access-token` After fixing, restart: ```shell kubectl rollout restart deployment/api --namespace develocity-provenance-governor kubectl rollout status deployment/api --namespace develocity-provenance-governor --timeout=90s ``` ## Verification and Next Steps After completing the deployment, verify that Develocity Provenance Governor is running correctly: 1. **Check Pod Status** ```shell kubectl get pods -n develocity-provenance-governor ``` You should see the `api` pod in `Running` state with `1/1` ready. 2. **Check Application Logs** ```shell kubectl logs deployment/api -n develocity-provenance-governor --tail=50 ``` Look for messages indicating: **License loaded successfully** Integrations enabled (e.g., "Develocity support enabled", "Artifactory support enabled") **Policies loaded (if configured)** No error messages 3. **Test API Accessibility** ```shell curl -i http://provenance-governor.acme.org ``` You should receive a `401 Unauthorized` response, which confirms the application is running and authentication is required. > [!NOTE] > The actuator endpoints (health, readiness, liveness, prometheus) are exposed on port 9090 and not accessible through the public ingress. Develocity Provenance Governor also exposes /livez and /readyz endpoints on the main application port for health checking when Kubernetes probes are enabled. 4. **Verify Integration Configuration** Check that your configured integrations were loaded: ```shell kubectl logs deployment/api -n develocity-provenance-governor | grep "support enabled" ``` > [!TIP] > Successfully deployed? If all verification steps passed and you’re ready to start using Develocity Provenance Governor, proceed to Publishing Attestations to learn how to publish attestations and evaluate policies. **What to Do Next:** * **Configure Your First Integration** - If you haven’t already, set up connections to Develocity and Artifactory. See [Application Configuration](https://docs.gradle.com/develocity/provenance-governor/1.7/app-config-overview/). * **Set Up Authentication** - Configure access control policies to secure your API. See [Access Control](#access-control). * **Write Your First Policy** - Define policies for your software supply chain governance. See [Writing Policies](https://docs.gradle.com/develocity/provenance-governor/1.7/writing-policies/). * **Publish Test Attestations** - Try publishing attestations for a test package. See [Publishing Attestations](https://docs.gradle.com/develocity/provenance-governor/1.7/publishing-attestations/). * **Integrate with CI/CD** - Add Develocity Provenance Governor to your build and deployment pipelines. See [GitHub Actions](https://docs.gradle.com/develocity/provenance-governor/1.7/ci-cd-integration/#github-actions) or [CI/CD Integration](https://docs.gradle.com/develocity/provenance-governor/1.7/ci-cd-integration/). If you encounter issues, consult the [Troubleshooting](https://docs.gradle.com/develocity/provenance-governor/1.7/troubleshooting/) section. ## Summary Cheat Sheet
IntegrationSecret Key PatternConfigMap Key PatternMandatoryNotes
License(file) develocity.licensen/aYesProvided via license secret
Registry Auth.dockerconfigjsonn/aYesJSON auth file for image pulls
Develocity Instancedevelocity.instances..access-keydevelocity.instances..uriNoMultiple supported
Artifactory Instanceartifactory.instances..access-tokenartifactory.instances..uriNoToken preferred
Signing Key (Private)signing.key..private-pemn/aNoBase64 PEM
Signing Key (Public)n/asigning.key..public-pemNoPEM block
Basic Identitybasic.identities.n/aNo{bcrypt} recommended
Policiesn/a.yaml in policies ConfigMapNoAccessControl docs