diff --git a/ships/0042-trusted-certificates b/ships/0042-trusted-certificates new file mode 100644 index 0000000..32ca922 --- /dev/null +++ b/ships/0042-trusted-certificates @@ -0,0 +1,121 @@ +# Trusted Certificates +## Release Signoff Checklist + +- [ ] Enhancement is `implementable` +- [ ] Design details are appropriately documented from clear requirements +- [ ] Test plan is defined +- [ ] Graduation criteria for dev preview, tech preview, GA +- [ ] User-facing documentation is created in [docs](/docs/) + +## Open Questions [optional] + + +## Summary + +This proposal aims to enhance Shipwright by allowing users to add user certificates in the build container's +OS trust store by extending the Build APIs to let user define a list of Kubernetes Secrets, which will hold the +certificate data and will be added to the trust store. +This capability is essential for scenarios requiring access to external resources like self-signed +certificates for Git/image registries or other necessary build artifacts, independent of BuildStrategy +definitions, overcoming a current limitation where all volumes must be pre-defined or overridable via the strategy. + +## Motivation + +Currently, Shipwright Builds face challenges when needing to utilize resources like self-signed +certificates for interacting with private Git repositories or image registries. + +### Goals + +- Extend Build resources API to declare a list of Secrets that hold separate certificate data. +- Ensure these directly defined volumes are mountable and accessible to all primary containers involved +in executing the build steps throughout the lifecycle of the build's execution Pod. + +### Non-Goals + +What is out of scope for this proposal? Listing non-goals helps to focus discussion and make +progress. + +## Proposal + +### User Stories + +#### Using self-signed certificates + +As a user, I want to use Git repositories or image registries that are secured with self-signed +certificates. These certificates need to be accessible by the build process, potentially across +multiple steps (e.g., source cloning, image push/pull). + +### Implementation Notes + +The current BuildRun APIs will be extended to support a list of certificates accepted as kubernetes Secret +resources, that should be loaded in the container's trust store. + +```yaml +apiVersion: shipwright.io/v1beta1 # Ensure this is the correct API group +kind: Build +metadata: + # ... +spec: + # ... + certificates: + - name: custom-cert-1 + secretName: ca-cert-1 + mountPath: /etc/ssl/cert # This is optional and will default to configuration from system parameter (see below) + - name: custom-cert-2 + secretName: ca-cert-2 +``` + +The default path where the certificates will be mounted is defined in the system parameter API of the build strategy. +https://shipwright.io/docs/build/buildstrategies/#system-parameters + +params.shp-certificate-directory + + + +If certificate with the same name is defined at multiple levels, the following precedence will apply +for its definition (e.g., which Secret or ConfigMap to use): + +- BuildRun.spec.certificates (highest precedence) +- Build.spec.certificates +- BuildStrategy.spec.certificates (lowest precedence, acts as a default or template) + + +- For new, directly mounted volumes, a mountPath must be specified. +- The name of the certificate must be unique within the list of certificates defined in any of Build, BuildRun, or BuildStatey. +- Standard Kubernetes validation for the source secret will apply. + + + +### Test Plan + +### Release Criteria + + +#### Upgrade Strategy [if necessary] + + +### Risks and Mitigations + +What are the risks of this proposal and how do we mitigate? Think broadly. For example, consider +both security and how this will impact the larger Shipwright ecosystem. + +How will security be reviewed and by whom? How will UX be reviewed and by whom? + +## Drawbacks + +TBD + +## Alternatives + +TBD + +## Infrastructure Needed [optional] + +Use this section if you need things from the project. Examples include a new subproject, repos +requested, github details, and/or testing infrastructure. + +Listing these here allows the community to get the process for these resources started right away. + +## Implementation History + +Major milestones in the life cycle of a proposal should be tracked in `Implementation History`.