SHIP-0042: Trusted certificates

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`.