-
Notifications
You must be signed in to change notification settings - Fork 1.8k
[WIP] OSDOCS-15575 added a new assembly and updated topic map #96769
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
wgabor0427
wants to merge
2
commits into
openshift:main
Choose a base branch
from
wgabor0427:OSDOCS-15575
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
11 changes: 11 additions & 0 deletions
11
modules/zero-trust-manager-cert-manager-upstream-authority.adoc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc | ||
|
|
||
| :_mod-docs-content-type: CONCEPT | ||
| [id="zero-trust-manager-cert-manager-upstream-authority_{context}"] | ||
| = About the cert-manager upstream authority plugin | ||
|
|
||
| The cert-manager plugin enables the SPIRE Server to dynamically request and receive intermediate signing certificates from cert-manager. The plugin automates the management of the SPIRE Server intermediate signing certificates by integrating with cert-manager. | ||
|
|
||
| When a SPIRE Server needs a new certificate, the cert-manager plugin creates a `CertificateRequest` custom resource in the configured {product-title} namespace. The namespace includes the Certificate Signing Request (CSR) generated by the SPIRE Server. The cert-manager plugin processes the `CertificateRequest` and an associated `Issuer` signs the Certificate Signing Request (CSR). The signed intermediate certificate and the full Certificate Authority (CA) bundle are available in the `CertificateRequest` status. These signed credentials are available to the SPIRE Server and used as its upstream signing authority. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc | ||
|
|
||
| :_mod-docs-content-type: CONCEPT | ||
| [id="zero-trust-manager-configure-cert-manager_{context}"] | ||
| = Configuring the cert-manager plugin | ||
|
|
||
| The cert-manager plugin for the SPIRE Server automates the intermediate signing certificates lifecycle of a SPIRE Server. The plugin manages the creation, renewal, and rotation of the signing certificates. | ||
|
|
||
| .Prerequisites | ||
|
|
||
| * Access to a {product-title} cluster where the SPIRE Server runs. | ||
|
|
||
| * cert-manager is installed and running within the Kubernetes cluster. For more information about installing cert-manager, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html-single/security_and_compliance/index#cert-manager-operator-install[Installing the cert-manager Operator for Red{nbsp}Hat OpenShift]. | ||
|
|
||
| * A pre-configured cert-manager `Issuer` capable of signing intermediate Certificate Authority (CA) certificates. | ||
|
|
||
| .Procedure | ||
|
|
||
| . Create a YAML file that defines the `SpireSever` CR object, for example, `SpireServer.yaml`: | ||
| + | ||
| .Example `SpireServer.yaml` | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: operator.openshift.io/v1alpha1 | ||
| kind: SpireServer | ||
| metadata: | ||
| name: cluster | ||
| spec: | ||
| trustDomain: example.com | ||
| upstreamAuthority: | ||
| type: cert-manager | ||
| certManager: | ||
| issuerKind: Issuer #<1> | ||
| issuerName: my-org-intermediate-ca #<2> | ||
| namespace: my-namespace #<3> | ||
| ---- | ||
|
|
||
| <1> Specifies the type of cert-manager issuer to use. The value `Issuer` indicates it is a namespace resource. The other option is `clusterIssuer`, which is a cluster-wide resource. | ||
| <2> The name of the `Issuer` or `CluserIssuer` resource within cert-manager that signs the certificate request. The issuer should already exist and configured to connect to the Public Key Infrastructure (PKI). | ||
| <3> Required when `issuerKind` is 'Issuer'. This field is omitted if using a `clusterIssuer`. | ||
|
|
||
| . Apply the configuration by running the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc apply -f SpireServer.yaml | ||
| ---- | ||
|
|
||
| .Verification | ||
|
|
||
| . Ensure that the resulting signed certificate and trust bundle are available in the secret created by the SPIRE Operator: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc get secret spire-server-server-ca -n spire -o yaml | ||
| ---- | ||
| + | ||
| .Example signed certificate and trust bundle | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: v1 | ||
| kind: Secret | ||
| metadata: | ||
| name: spire-server-server-ca | ||
| namespace: spire | ||
| ownerReferences: | ||
| - apiVersion: spire.spiffe.io/v1alpha1 | ||
| kind: SpireServer | ||
| name: spire-server | ||
| # ... | ||
| type: Opaque | ||
| data: <1> | ||
| <trust_bundle> <2> | ||
| ca.crt: | ||
| <intermediate_CA_certificate> <3> | ||
| ca.key: | ||
| <private_key> | ||
| ---- | ||
| <1> The trust bundle containing the root CA and the intermediate CA. | ||
| <2> The SPIRE Server's intermediate CA certificate signed by your Issuer. | ||
| <3> The private key for the SPIRE Server's intermediate CA. | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc | ||
|
|
||
| :_mod-docs-content-type: PROCEDURE | ||
| [id="zero-trust-manager-configure-issuer_{context}"] | ||
|
|
||
| = Configuring the cert-manager issuer | ||
|
|
||
| Before you can configure the cert-manager plugin, you need to create an `Issuer` since the `Issuer` represents the Certificate Authority (CA) and defines how certificates are issued. | ||
|
|
||
| .Prerequisites | ||
|
|
||
| * cert-manager is installed and running within the {product-tile} cluster. For more information about installing cert-manager, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html-single/security_and_compliance/index#cert-manager-operator-install[Installing the cert-manager Operator for Red{nbsp}Hat OpenShift]. | ||
|
|
||
|
|
||
| .Procedure | ||
|
|
||
| Create a cert-manager `Issuer` by performing the following steps: | ||
|
|
||
| . Generate the Transport Layer Security (TLS) Secret by running the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc create secret tls my-ca-key-pair-secret \ | ||
| --cert=path/to/your/ca.crt \ | ||
| --key=path/to/your/ca.key \ | ||
| --namespace=my-namespace | ||
| ---- | ||
|
|
||
| . Create a YAML file that defines the `Issuer`, for example `ca-issuer.yaml`: | ||
| + | ||
| .Example `ca-issuer.yaml` | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: cert-manager.io/v1 | ||
| kind: Issuer | ||
| metadata: | ||
| name: my-ca-issuer | ||
| namespace: my-namespace | ||
| spec: | ||
| ca: | ||
| secretName: my-ca-key-pair-secret <1> | ||
| ---- | ||
| <1> The name of the Kubernetes Secret that holds the `tls.cert` and `tls.key` files. This secret must exist before you create the `Issuer`. | ||
|
|
||
| . Apply the configuration by running the following command: | ||
| + | ||
| [source, terminal] | ||
| ---- | ||
| $ oc apply -f ca-issuer.yaml | ||
| ---- | ||
|
|
||
| .Verification | ||
| To verify that the `Issuer` is created, run the following command: (IS THIS CORRECT OR HOW DO WE VERIFY IT) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * security/zero_trust_workload_identity_manager/zero-trust-manager.adoc | ||
|
|
||
| :_mod-docs-content-type: PROCEDURE | ||
| [id="zero-trust-manager-configure-cert-vault_{context}"] | ||
| = Configuring the Vault plugin | ||
|
|
||
| This procedure outlines the steps required to configure a SPIRE Server to obtain its intermediate signing certificates from HashiCorp Vault. The plugin supports the following methods for authenticating to Vault: | ||
|
|
||
| * Client Certificate Authentication | ||
|
|
||
| * Token Authentication | ||
|
|
||
| * `AppRole` Authentication | ||
|
|
||
| * Kubernetes Authentication | ||
|
|
||
| .Prerequisites | ||
|
|
||
| * A running and accessible HashiCorp Vault Server is available. | ||
|
|
||
| * A PKI secret engine is enabled and configured in Vault at the specified `pki_mount_point`. | ||
|
|
||
| * A role within the Vault PKI engine must be configured to allow issuing of intermediate CA certificates. | ||
|
|
||
| * The Vault token or authentication method used by the plugin must have the necessary permissions. | ||
|
|
||
| * The `ca_ttl` property configured in your SPIRE Server configuration must be less than or equal to the configured `max_lease_ttl` of the Vault PKI secret engine role that the plugin uses. | ||
|
|
||
| .Procedure | ||
|
|
||
| . Create a YAML file containing the configuration for the `SpireServer` resource, for example `SpireServer.yaml`. The file includes the `spec` block and the `upstreamAuthority` block configured to use the `vault` plugin. | ||
| + | ||
| .Example `SpireServer.yaml` | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: spire.spiffe.io/v1alpha1 | ||
| kind: SpireServer | ||
| metadata: | ||
| name: spire-server | ||
| namespace: spire | ||
| spec: | ||
| replicas: 1 | ||
| upstreamAuthority: | ||
| vault:# | ||
| address: "https://vault.example.com" <1> | ||
| tokenPath: "/var/run/secrets/kubernetes.io/serviceaccount/token" <2> | ||
| mtls: | ||
| spireTrustDomain: "spiffe://example.org" <3> | ||
| serverName: "vault.example.com" <4> | ||
| pkcs11: | ||
| jwt: | ||
| ---- | ||
| + | ||
| <1> The URL of your Vault server. | ||
| <2> The path to the Kubernetes service account token used for authentication with Vault. | ||
| <3> The trust domain of your Spire Server. | ||
| <4> The name used for Mutual Transport Layer Security (mTLS) authentication with the Vault server. | ||
|
|
||
| . Configure one of the authentication methods: | ||
| .. Configure the `certAuth` authentication in the `upstreamAuthority` section of the `SpireServer.yaml` file. This method uses a client certificate and private key for authentication. | ||
| + | ||
| .Example `certAuth` | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| # ... | ||
| upstreamAuthority: | ||
| vault: | ||
| certAuth: | ||
| certAuthMountPoint: "cert" <1> | ||
| clientCertSecret: "vault-client-cert-secret" <2> | ||
| clientKeySecret: "vault-client-key-secret" <3> | ||
| certAuthRoleName: "spire-server-role" <4> | ||
| ---- | ||
| + | ||
| <1> The mount point where the TLS certificate auth method is enabled. | ||
| <2> Name of the Kubernetes secret containing the client certificate in Privacy Enhanced Mail (PEM) format. | ||
| <3> Name of the Kubernetes secret containing the client private key in PEM format. | ||
| <4> The name of the Vault role to authenticate against. | ||
|
|
||
| .. Configure the `tokenAuth` authentication in the `spstreamAuthority` section of the `SpireServer.yaml` file. This method uses a static Vault token. | ||
| + | ||
| .Example `tokenAuth` | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| # ... | ||
| upstreamAuthority: | ||
| vault: | ||
| tokenAuth: | ||
| token: "hvs.YOUR_VAULT_TOKEN_HERE" | ||
| ---- | ||
|
|
||
| .. Configure the `appRoleAuth` authentication in the `upstreamAuthority` section of the `SpireServer.yaml` file. This method uses the `AppRole` for Vault. | ||
| + | ||
| .Example `tokenAuth` | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| # ... | ||
| upstreamAuthority: | ||
| vault: | ||
| appRoleAuth: | ||
| appRoleMountPoint: "approle" <1> | ||
| appRoleID: "your-approle-id" <2> | ||
| appRoleSecretID: "your-approle-secret-id" <3> | ||
| ---- | ||
| + | ||
| <1> The mount point where the `AppRole` auth method is enabled. | ||
| <2> The `appRoleID` used for authentication. | ||
| <3> the `appRoleSecretID` used for authentication. | ||
|
|
||
| . Configure the `k8sAuth` authentication in the `upstreamAuthority` section of the `SpireServer.yaml` file. This method uses a Kubernetes `ServiceAccount` token for authentication. | ||
| + | ||
| .Example `tokenAuth` | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| # ... | ||
| upstreamAuthority: | ||
| vault: | ||
| k8sAuth: | ||
| k8sAuthMountPoint: "kubernetes" <1> | ||
| k8sAuthRoleName: "spire-server-k8s-role" <2> | ||
| tokenPath: "/var/run/secrets/kubernetes.io/serviceaccount/token" <3> | ||
| ---- | ||
| + | ||
| <1> The mount point where the Kubernetes auth method is enabled. | ||
| <2> The name of the Vault role the plugin authenticates against. | ||
| <3> The path to the Kubernetes `ServiceAccount` token file. | ||
|
|
||
| . Apply the configuration by running the following command: | ||
| + | ||
| [source, terminal] | ||
| ---- | ||
| $ oc apply -f spireserver.yaml | ||
| ---- | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc | ||
|
|
||
| :_mod-docs-content-type: CONCEPT | ||
| [id="zero-trust-manager-vault-upstream-authority_{context}"] | ||
| = About the Vault upstream authority plugin | ||
|
|
||
| The Vault plugin integrates the SPIRE Server with the HashiCorp Vault Public Key Infrastructure (PKI) engine to manage the lifecycle of intermediate CA certificates. The SPIRE Server uses the CA certificates to sign the workload {svid-full}. The plugin enables the SPIRE Server to use the PKI for issuing and renewing intermediate signing certificates. | ||
|
|
||
| The plugin interacts with the PKI secret engine to request intermediate CA certificates, signs the requests, and then provides the certificates to the SPIRE Server. | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| The Vault plugin does not support the `PublishJWTKey` remote procedure call (RPC) and should not be used in SPIRE configurations where JSON Web Tokens-SPIFFE Verifiable Identity Documents (JWT-SVIDs) are used. | ||
| ==== |
40 changes: 40 additions & 0 deletions
40
...zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority.adoc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| :_mod-docs-content-type: ASSEMBLY | ||
| [id="zero-trust-manager-upstream-authority-plugins"] | ||
| = Zero Trust Workload Identity Manager upstream authority plugins | ||
|
|
||
| include::_attributes/common-attributes.adoc[] | ||
| :context: zero-trust-manager-overview | ||
|
|
||
| toc::[] | ||
|
|
||
| :FeatureName: Zero Trust Workload Identity Manager | ||
| include::snippets/technology-preview.adoc[] | ||
|
|
||
| Upstream authority plugins are components that allow the SPIRE Server to integrate with an existing Public Key Infrastructure (PKI) to obtain intermediate signing certificates. The SPIRE Server then uses these intermediate certificates to cryptographically sign the {svid-full} that it issues to workloads. The plugins also allow the SPIRE Server to use a pre-existing root of trust, rather than establishing a new, isolated root of trust. | ||
|
|
||
| The following upstream authority plugins are available: | ||
|
|
||
| * cert-manager | ||
|
|
||
| * vault | ||
|
|
||
| == Configuring the cert-manager plugin | ||
|
|
||
| // About the cert-manager plug in | ||
| include::modules/zero-trust-manager-cert-manager-upstream-authority.adoc[leveloffset=+1] | ||
|
|
||
| // Configuring an issuer | ||
| include::modules/zero-trust-manager-configure-issuer.adoc[leveloffset=+1] | ||
|
|
||
| // Configuring the cert-manager plugin | ||
| include::modules/zero-trust-manager-configure-cert-manager.adoc[leveloffset=+1] | ||
|
|
||
| == Configuring the Vault plugin | ||
|
|
||
| // About the vault plug in | ||
| include::modules/zero-trust-manager-vault-upstream-authority.adoc[leveloffset=+1] | ||
|
|
||
| // Configuring the vault plugin | ||
| include::modules/zero-trust-manager-configure-vault.adoc[leveloffset=+1] | ||
|
|
||
|
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There are a lot of assumptions that the Vault server has been configured a certain way. Is there any other guidance that we will be providing for our customers?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do not know that. Yuedong would have to confirm