Add initial documentation for the helm-charts-hardened chart (#290)

* Adds PR template Signed-off-by: Maximiliano Churichi <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Add support for building/testing with podman Signed-off-by: Kevin Fox <[email protected]> * Add initial documentation for the help-charts-hardened chart Signed-off-by: Kevin Fox <[email protected]> * Add ingress documentation Signed-off-by: Kevin Fox <[email protected]> * Add basic federation docs and misc fixes Signed-off-by: Kevin Fox <[email protected]> * Add recommendations, some nested spire docs, and misc changes Signed-off-by: Kevin Fox <[email protected]> * Remove unneeded bits Signed-off-by: Kevin Fox <[email protected]> * Add Namespace documentation Signed-off-by: Kevin Fox <[email protected]> * Add initial mirroring docs Signed-off-by: Kevin Fox <[email protected]> * Update docs for external agents Signed-off-by: Kevin Fox <[email protected]> * Can't use controller manager with join tokens Signed-off-by: Kevin Fox <[email protected]> * More examples Signed-off-by: Kevin Fox <[email protected]> * Make image better Signed-off-by: Kevin Fox <[email protected]> * Update diagrams Signed-off-by: Kevin Fox <[email protected]> * Update things Signed-off-by: Kevin Fox <[email protected]> * Reorder docs Signed-off-by: Kevin Fox <[email protected]> * More updates Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Add join token details Signed-off-by: Kevin Fox <[email protected]> * Update Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Better diagram Signed-off-by: Kevin Fox <[email protected]> * Break out ready docs from nonready Signed-off-by: Kevin Fox <[email protected]> * Update content/docs/latest/spire-helm-charts-hardened-about/installation.md Signed-off-by: Kevin Fox <[email protected]> * Fix typo Signed-off-by: Kevin Fox <[email protected]> * Add support for building/testing with podman (#289) * Add support for building/testing with podman Signed-off-by: Kevin Fox <[email protected]> * Update Makefile Signed-off-by: kfox1111 <[email protected]> --------- Signed-off-by: Kevin Fox <[email protected]> Signed-off-by: kfox1111 <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Update content/docs/latest/spire-helm-charts-hardened-about/exposing.md Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Update content/docs/latest/spire-helm-charts-hardened-about/exposing.md Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Update content/docs/latest/spire-helm-charts-hardened-about/identifiers.md Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Signed-off-by: Kevin Fox <[email protected]> * Removed HeadBucket Signed-off-by: Quintessence <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Update install instructions Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Co-authored-by: Faisal Memon <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Signed-off-by: Kevin Fox <[email protected]> Co-authored-by: Maximiliano Churichi <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Update content/docs/latest/spire-helm-charts-hardened-about/recommendations.md Signed-off-by: Kevin Fox <[email protected]> * add VMware Secrets Manager as a consumer (#301) Signed-off-by: Volkan Özçelik <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> * Apply suggestions from code review Signed-off-by: Kevin Fox <[email protected]> Co-authored-by: Maximiliano Churichi <[email protected]> Signed-off-by: Kevin Fox <[email protected]> * Incorperate feedback Signed-off-by: Kevin Fox <[email protected]> --------- Signed-off-by: Maximiliano Churichi <[email protected]> Signed-off-by: Kevin Fox <[email protected]> Signed-off-by: kfox1111 <[email protected]> Signed-off-by: Quintessence <[email protected]> Signed-off-by: Volkan Özçelik <[email protected]> Co-authored-by: Maximiliano Churichi <[email protected]> Co-authored-by: Faisal Memon <[email protected]> Co-authored-by: Quintessence <[email protected]> Co-authored-by: Volkan Özçelik <[email protected]>
spiffe · Apr 3, 2024 · 2aa1e90 · 2aa1e90
1 parent aec8b6d
commit 2aa1e90
Show file tree

Hide file tree

Showing 13 changed files with 927 additions and 0 deletions.
diff --git a/content/docs/latest/spire-helm-charts-hardened-about/_index.md b/content/docs/latest/spire-helm-charts-hardened-about/_index.md
@@ -0,0 +1,14 @@
+---
+title: About SPIRE Helm Charts Hardened
+short: About
+kind: spire-helm-charts-hardened-about
+aliases:
+    - /spire-helm-charts-hardened
+---
+
+The [SPIRE Helm chart](https://artifacthub.io/packages/helm/spiffe/spire) provided by the [helm-charts-hardened](https://github.com/spiffe/helm-charts-hardened) project is an easy and supported way to deploy a complete SPIRE stack in Kubernetes.
+
+Out of the box, it deploys the SPIRE Server, SPIRE Agent, SPIRE Controller Manager, SPIFFE CSI Driver, and SPIFFE OIDC Discovery Provider along with configuring them all to integrate with the Kubernetes
+cluster it is running on.
+
+{{< sectiontoc "spire-helm-charts-hardened-about" >}}
diff --git a/content/docs/latest/spire-helm-charts-hardened-about/exposing.md b/content/docs/latest/spire-helm-charts-hardened-about/exposing.md
@@ -0,0 +1,107 @@
+---
+title: Exposing Services
+short: Exposing Services
+description: How to expose SPIFFE/SPIRE services outside of Kubernetes
+kind: spire-helm-charts-hardened-about
+weight: 150
+aliases:
+    - /docs/latest/helm-charts-hardened/exposing
+---
+
+# Default
+
+By default no SPIRE services are exposed outside the Kubernetes cluster. The below sections cover how to expose them.
+
+
+# Exposable Services
+
+## Production Services
+
+| Service Name                     | Section Value                          | Default DNS Name                     |
+| -------------------------------- | -------------------------------------- | ------------------------------------ |
+| SPIRE Server                     | spire-server.ingress                   | spire-server.$trustDomain            |
+| SPIRE Federation Bundle Endpoint | spire-server.federation.ingress        | spire-server-federation.$trustDomain |
+| SPIFFE OIDC Discovery Provider   | spiffe-oidc-discovery-provider.ingress | oidc-discovery.$trustDomain          |
+
+## Experimental Services
+
+| Service Name                     | Value                                  | Default DNS Name                     |
+| -------------------------------- | -------------------------------------- | ------------------------------------ |
+| Tornjak Frontend                 | tornjak-frontend.ingress               | tornjak-backend.$trustDomain         |
+| Tornjak Backend                  | spire-server.tornjak.ingress           | tornjak-frontend.$trustDomain        |
+
+# Ingress Controller Support
+
+We have tests for ingress-nginx based Ingress Controllers and the Ingress Controller built into OpenShift.
+
+For ingress-nginx, set `global.spire.ingressControllerType=ingress-nginx`
+
+For OpenShift, set `global.openshift=true`
+
+Other Ingress Controllers may work but are untested and unsupported. Set the
+`ingress.annotations` values as appropriate for your Ingress Controller. Please consider [submitting a PR](https://github.com/spiffe/helm-charts-hardened/pulls) if you're able to get another Ingress to work.
+
+# Generic Ingress Config
+
+Each Ingress that is enabled by setting `ingress.enabled=true` will by default create a virtual host with a DNS name like
+`$serviceName.$trustDomain`. You can override the host under the services ingress section with key host. If the host
+value doesn't have a `.` in it, $trustDomain will automatically be added.
+
+Example: Overriding the spire-server-federation host to be `example-fed.$trustDomain`
+
+your-values.yaml snippet:
+```yaml
+spire-server:
+ federation:
+   ingress:
+     enabled: true
+     host: example-fed
+```
+
+Example: Overriding the spire-server-federation host to be `example-fed.my-domain.com`
+
+your-values.yaml snippet:
+```yaml
+spire-server:
+ federation:
+   ingress:
+     enabled: true
+     host: example-fed.my-domain.com
+```
+
+# SPIFFE OIDC Discovery Provider
+
+The most likely service you will want to expose outside the Kubernetes Cluster is the the SPIFFE OIDC Discovery Provider.
+
+In order to check the integrity of a JWT, an external service needs information about the server used to sign the
+JWT. This info can be retrieved from the SPIFFE OIDC Discovery Provider. It will need to be exposed to any other
+service needing to validate JWT's.
+
+# SPIRE Server
+
+When setting up a Nested SPIRE installation and you have child SPIRE instances in other clusters, you will need to
+expose the Root SPIRE instance outside the Kubernetes cluster. You can do this like:
+
+your-values.yaml snippet:
+```yaml
+spire-server:
+  ingress:
+    enabled: true
+```
+
+# SPIRE Federation Bundle Endpoint
+
+When setting up Federation, you need to expose the bundle endpoint outside the Kubernetes cluster so other SPIRE
+instances can contact it.  It will not work without enabling Federation as well. Please see the
+[Federation documentation](/docs/latest/spire-helm-charts-hardened-advanced/federation/) of the Helm Chart for
+all the related options to successfully deploy a Federation.
+
+your-values.yaml snippet:
+```yaml
+spire-server:
+  federation:
+    enabled: true
+    ingress:
+      enabled: true
+```
+
diff --git a/content/docs/latest/spire-helm-charts-hardened-about/identifiers.md b/content/docs/latest/spire-helm-charts-hardened-about/identifiers.md
@@ -0,0 +1,155 @@
+---
+title: Identifiers
+short: Identifiers
+description: How to configure SPIFFE IDs
+kind: spire-helm-charts-hardened-about
+weight: 200
+aliases:
+    - /docs/latest/helm-charts-hardened/identifiers
+---
+
+## Defaults
+
+- The chart deploys [SPIRE Controller Manager](https://github.com/spiffe/spire-controller-manager) to manage SPIFFE Identifiers by Kubernetes Custom Resources.
+- The chart deploys a ClusterSPIFFEID Custom Resource that gives an identifier to all pods of the form `spiffe://{{ .TrustDomain }}/ns/{{ .PodMeta.Namespace }}/sa/{{ .PodSpec.ServiceAccountName }}`.
+- For a lot of use cases you don't need to add additional identifiers.
+
+## Custom / Additional Identifiers
+
+In some cases you may want to customize your identifiers or add additional ones.
+
+The chart supports managing the Custom Resources from the charts values file for even easier management. We recommend using values for customization.
+
+While you can manage identities using the [Kubernetes Custom Resources](https://github.com/spiffe/spire-controller-manager?tab=readme-ov-file#custom-resources) directly,
+we do not recommend doing that as it takes care to not misconfigure.
+
+## Restricting the default SVIDs
+
+Some workloads only reliably support one SVID at a time. To support customization you can do either two things:
+
+1. You can disable the default ClusterSPIFFEID entirely and load in individual ClusterSPIFFEIDs for each workload/namespace.
+2. Restrict the namespaces the default ClusterSPIFFEID applies to, so new ClusterSPIFFEIDs can uniquely match the workload in the excluded namespaces.
+
+### Disabling the default ClusterSPIFFEIDs
+
+your-values.yaml snippet:
+```yaml
+spire-server:
+  controllerManager:
+    identities:
+      clusterSPIFFEIDs:
+        default:
+          enabled: false
+```
+
+### Restricting the default ClusterSPIFFEIDs
+
+Example: Exclude the default ClusterSPIFFEID from getting applied to the `dev` and `test` namespaces
+
+your-values.yaml snippet:
+```yaml
+spire-server:
+  controllerManager:
+    identities:
+      clusterSPIFFEIDs:
+        default:
+          namespaceSelector:
+            matchExpressions:
+            - key: "kubernetes.io/metadata.name"
+              operator: NotIn
+              values: [dev, test]
+```
+
+# Dynamic SVIDs
+
+Additional ClusterSPIFFEIDs can be added to the cluster by adding additional keys / values under the `spire-server.controllerManager.identities.clusterSPIFFEIDs` dictionary.
+
+Example: Add a SVID that matches the workload labeled `app: frontend` in namespace `test` and add a DNS entry to it named `frontend.example.com`:
+
+your-values.yaml snippet:
+```yaml
+spire-server:
+  controllerManager:
+    identities:
+      clusterSPIFFEIDs:
+        test-frontend:
+          namespaceSelector:
+            matchExpressions:
+            - key: "kubernetes.io/metadata.name"
+              operator: In
+              values: [test]
+          podSelector:
+            matchLabels:
+              app: frontend
+          dnsNameTemplates:
+          - frontend.example.com
+```
+
+# Static SVIDs
+
+## Regular SVIDs
+
+Generally, loading Static SVIDS is only useful when using a workload attestor that is not the Kubernetes attestor. (non default settings)
+
+Example: Add a SVID that matches processes running under gid `1000` on node `x` and give it a spiffeID of `spiffe://example.com/frontend` with dns name `frontend.example.com`
+
+your-values.yaml snippet:
+```yaml
+spire-server:
+  controllerManager:
+    identities:
+      clusterStaticEntries:
+        frontend:
+          parentID: spiffe://example.com/node/x
+          spiffeID: spiffe://example.com/frontend
+          selectors:
+          - unix:gid:1000
+          dnsNameTemplates:
+          - frontend.example.com
+```
+
+## Node SVIDs
+
+When using a node attestor other then k8sPsat, you may need to add some node entries to the database. You can make static entries for them by using the SPIRE Server's identity
+as the parent. To link up to the k8sPsat
+
+Example:
+
+your-values.yaml snippet:
+```yaml
+spire-server:
+  controllerManager:
+    identities:
+      clusterStaticEntries:
+        node1:
+          parentID: spiffe://example.org/spire/server
+          spiffeID: spiffe://example.org/spire/agent/k8s_psat/example-cluster/e860cb09-8533-4f2e-80dc-8286d768c992
+          selectors:
+          - tpm:pub_hash:646789aab7a9028713b8fa5197cf6be0e935d7da048866f86224ec64c50d590c
+        node2:
+          parentID: spiffe://example.org/spire/server
+          spiffeID: spiffe://example.org/spire/agent/k8s_psat/example-cluster/8494d54e-6ad5-4c8e-87d1-2e6b7c2315cc
+          selectors:
+          - tpm:pub_hash:d2f0ac3a4ad72e0f14f3cd7d6b5cab16c06dc05a6b847a03c8771d640709eadd
+        node3:
+          parentID: spiffe://example.org/spire/server
+          spiffeID: spiffe://example.org/spire/agent/k8s_psat/example-cluster/5afebd69-7c67-4998-a953-f491c156ee35
+          selectors:
+          - tpm:pub_hash:ac951f972127d8176c367bba4684e57da3589d1f0e072a608d53977255503c7f
+```
+
+## Join Tokens
+
+When using the spire-controller-manager, do not use the `-spiffeID` flag to `spire-server token generate`. It will get undone by the controller manager. To use, generate the token
+then add to your-values.yaml
+```yaml
+spire-server:
+  controllerManager:
+    identities:
+      clusterStaticEntries:
+        node123:
+          spiffeID: spiffe://example.org/your-identifier-here
+          parentID: spiffe://example.org/spire/agent/join_token/3b6c7dcf-10de-406c-9733-f22846f3addb
+          selectors:
+          - spiffe_id:spiffe://example.org/spire/agent/join_token/3b6c7dcf-10de-406c-9733-f22846f3addb
+```
diff --git a/content/docs/latest/spire-helm-charts-hardened-about/installation.md b/content/docs/latest/spire-helm-charts-hardened-about/installation.md
@@ -0,0 +1,69 @@
+---
+title: Installation
+short: Installation
+description: How to install the SPIRE stack using the SPIRE Helm charts
+kind: spire-helm-charts-hardened-about
+weight: 100
+aliases:
+    - /docs/latest/helm-charts-hardened/installation
+---
+
+## Quick start
+
+To do a quick install suitable for non production environments such as [minikube](https://minikube.sigs.k8s.io/docs/):
+
+```
+helm upgrade --install --create-namespace -n spire spire-crds spire-crds \
+ --repo https://spiffe.github.io/helm-charts-hardened/
+
+helm upgrade --install -n spire spire spire \
+ --repo https://spiffe.github.io/helm-charts-hardened/
+```
+
+## Production Deployment
+
+Preparing a production deployment requires a few extra steps.
+
+1. Save the following to your-values.yaml, ideally in your git repo.
+```yaml
+global:
+  openshift: false # If running on openshift, set to true
+  spire:
+    recommendations:
+      enabled: true
+    namespaces:
+      create: true
+    ingressControllerType: "" # If not openshift, and want to expose services, set to a supported option [ingress-nginx]
+    # Update these
+    clusterName: example-cluster
+    trustDomain: example.org
+    caSubject:
+      country: ARPA
+      organization: Example
+      commonName: example.org
+```
+
+2. If you need a non default storageClass, append the following to the spire-server section and update:
+```
+  persistence:
+    storageClass: your-storage-class
+```
+
+3. If your Kubernetes cluster is OpenShift based, use the output of the following command to update the trustDomain setting:
+```shell
+oc get cm -n openshift-config-managed  console-public -o go-template="{{ .data.consoleURL }}" | \
+  sed 's@https://@@; s/^[^.]*\.//'
+```
+
+4. Find any additional values you might want to set based on the documentation on this site or the [examples](https://github.com/spiffe/helm-charts-hardened/tree/main/examples). In particular, consider using an external database.
+
+5. Deploy
+
+```shell
+helm upgrade --install --create-namespace -n spire-mgmt spire-crds spire-crds \
+  --repo https://spiffe.github.io/helm-charts-hardened/
+
+helm upgrade --install -n spire-mgmt spire spire \
+ --repo https://spiffe.github.io/helm-charts-hardened/ \
+ -f your-values.yaml
+```