Skip to content

Commit

Permalink
update docs/README
Browse files Browse the repository at this point in the history
  • Loading branch information
@sallyom
sallyom committed Dec 11, 2023
1 parent 3ca1ba1 commit fed7a21
Show file tree
Hide file tree
Showing 7 changed files with 169 additions and 30 deletions.
7 changes: 5 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,11 @@ This chart extends all the features in the upstream chart in addition to includi

### Installing from the Chart Repository

For a quickstart on how to install Sigstore components on OpenShift refer to the
[quickstart quide](docs/quick-start-with-keycloak.md)
For a quickstart on how to install Sigstore components on OpenShift with OpenShift SSO (Keycloak), refer to the
[quickstart quide with keycloak](docs/quick-start-with-keycloak.md)

For a quickstart on how to install Sigstore components on OpenShift with the upstream Sigstore OIDC Issuer URL, refer to the
[quickstart quide](docs/quick-start-with-sigstore-issuer.md)

## Scaffolding Chart

Expand Down
2 changes: 1 addition & 1 deletion charts/trusted-artifact-signer/Chart.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,4 @@ sources:
# This is the chart version. This version number should be incremented each time you make changes
# to the chart and its templates, including the app version.
# Versions are expected to follow Semantic Versioning (https://semver.org/)
version: 0.1.29
version: 0.1.30
55 changes: 41 additions & 14 deletions charts/trusted-artifact-signer/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,17 @@

A Helm chart for deploying Sigstore scaffold chart that is opinionated for OpenShift

![Version: 0.1.29](https://img.shields.io/badge/Version-0.1.29-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square)
![Version: 0.1.30](https://img.shields.io/badge/Version-0.1.30-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square)

## Overview

This wrapper chart builds on top of the [Scaffold](https://github.com/sigstore/helm-charts/tree/main/charts/scaffold)
chart from the Sigstore project to both simplify and satisfy the requirements for deployment within an OpenShift

If you have already read this document and want a quick no-fail path to installing a Sigstore stack with RH SSO,
Refer to the quick-start to install Sigstore components on OpenShift with the upstream Sigstore OIDC Issuer URL,
[quickstart quide](docs/quick-start-with-sigstore-issuer.md)

For a quick no-fail path to installing a Sigstore stack with RH SSO,
follow [quick start](../../docs/quick-start-with-keycloak.md)

The chart enhances the scaffold chart by taking care of the following:
Expand All @@ -35,15 +38,48 @@ scaffold:

### Sample Implementation

#### Prerequisites

The following must be satisfied prior to deploying the sample implementation:
The installer and the quick start with RedHat SSO script include the creation of the necessary secrets:

* Fulcio root CA certificate and signing keys
* More information in [requirements-keys-certs.md](../../docs/requirements-keys-certs.md)
* OpenID Token Issuer endpoint
* The public Sigstore OIDC Issuer URL `https://oauth2.sigstore.dev/auth` is configured in the absence of any other OIDC provider.
* Keycloak/RHSSO requirements can be followed and deployed in OpenShift with [keycloak-example.md](../../docs/keycloak-example.md)

To add configuration options to the TAS installation, either provide a custom `values.yaml` or provide available flags to the `tas-install`
command.

#### Configure the install with the `tas-install` command flags.

Here are the available options for use with `tas-install`. For any other customization, you may provide a `values.yaml` with necessary
information.

```
$ ./tas-install install -h
Installs Trusted Artifact Signer (TAS) on a Kubernetes cluster.
This command performs a series of actions:
1. Initializes the Kubernetes client to interact with your cluster
2. Sets up necessary certificates
3. Configures secrets
4. Deploys TAS to openshift
Usage:
tas-installer install [flags]
Flags:
--chart-location string /local/path/to/chart or oci://registry/repo location of Helm chart (default "./charts/trusted-artifact-signer")
--chart-version string Version of the Helm chart (default "0.1.29")
-h, --help help for install
--oidc-client-id string Specify the OIDC client ID
--oidc-issuer-url string Specify the OIDC issuer URL e.g for keycloak: https://[keycloak-domain]/auth/realms/[realm-name]
--oidc-type string Specify the OIDC type
--values string path to custom values file for chart configuration
Global Flags:
--kubeconfig string Specify the kubeconfig path (default "/Users/somalley/.kube/config")
```

#### Update the values file

Helm values files are available in the examples directory that provides a baseline to work off of.
Expand All @@ -55,15 +91,6 @@ to curate the deployment of the chart:

2. Perform any additional customizations as desired

### Installing the Chart

When logged in as an elevated OpenShift user, execute the following to install the chart referencing the
customized values file. The OPENSHIFT_APPS_SUBDOMAIN will be substituted in the values file with `envsubst` below:

```shell
OPENSHIFT_APPS_SUBDOMAIN=apps.$(oc get dns cluster -o jsonpath='{ .spec.baseDomain }') envsubst < examples/values-sigstore-openshift.yaml | helm upgrade -i trusted-artifact-signer --debug charts/trusted-artifact-signer -n sigstore --create-namespace --values -
```

### Monitor Sigstore Components with Grafana

For real-time analytics through Grafana, refer to our [enable-grafana-monitoring.md](../../docs/enable-grafana-monitoring.md) guide.
Expand Down
52 changes: 40 additions & 12 deletions charts/trusted-artifact-signer/README.md.gotmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,10 @@
This wrapper chart builds on top of the [Scaffold](https://github.com/sigstore/helm-charts/tree/main/charts/scaffold)
chart from the Sigstore project to both simplify and satisfy the requirements for deployment within an OpenShift

If you have already read this document and want a quick no-fail path to installing a Sigstore stack with RH SSO,
Refer to the quick-start to install Sigstore components on OpenShift with the upstream Sigstore OIDC Issuer URL,
[quickstart quide](docs/quick-start-with-sigstore-issuer.md)

For a quick no-fail path to installing a Sigstore stack with RH SSO,
follow [quick start](../../docs/quick-start-with-keycloak.md)

The chart enhances the scaffold chart by taking care of the following:
Expand All @@ -33,15 +36,48 @@ scaffold:

### Sample Implementation

#### Prerequisites

The following must be satisfied prior to deploying the sample implementation:
The installer and the quick start with RedHat SSO script include the creation of the necessary secrets:

* Fulcio root CA certificate and signing keys
* More information in [requirements-keys-certs.md](../../docs/requirements-keys-certs.md)
* OpenID Token Issuer endpoint
* The public Sigstore OIDC Issuer URL `https://oauth2.sigstore.dev/auth` is configured in the absence of any other OIDC provider.
* Keycloak/RHSSO requirements can be followed and deployed in OpenShift with [keycloak-example.md](../../docs/keycloak-example.md)

To add configuration options to the TAS installation, either provide a custom `values.yaml` or provide available flags to the `tas-install`
command.

#### Configure the install with the `tas-install` command flags.

Here are the available options for use with `tas-install`. For any other customization, you may provide a `values.yaml` with necessary
information.

```
$ ./tas-install install -h
Installs Trusted Artifact Signer (TAS) on a Kubernetes cluster.

This command performs a series of actions:
1. Initializes the Kubernetes client to interact with your cluster
2. Sets up necessary certificates
3. Configures secrets
4. Deploys TAS to openshift

Usage:
tas-installer install [flags]

Flags:
--chart-location string /local/path/to/chart or oci://registry/repo location of Helm chart (default "./charts/trusted-artifact-signer")
--chart-version string Version of the Helm chart (default "0.1.29")
-h, --help help for install
--oidc-client-id string Specify the OIDC client ID
--oidc-issuer-url string Specify the OIDC issuer URL e.g for keycloak: https://[keycloak-domain]/auth/realms/[realm-name]
--oidc-type string Specify the OIDC type
--values string path to custom values file for chart configuration

Global Flags:
--kubeconfig string Specify the kubeconfig path (default "/Users/somalley/.kube/config")
```

#### Update the values file

Helm values files are available in the examples directory that provides a baseline to work off of.
Expand All @@ -53,14 +89,6 @@ to curate the deployment of the chart:

2. Perform any additional customizations as desired

### Installing the Chart

When logged in as an elevated OpenShift user, execute the following to install the chart referencing the
customized values file. The OPENSHIFT_APPS_SUBDOMAIN will be substituted in the values file with `envsubst` below:

```shell
OPENSHIFT_APPS_SUBDOMAIN=apps.$(oc get dns cluster -o jsonpath='{ .spec.baseDomain }') envsubst < examples/values-sigstore-openshift.yaml | helm upgrade -i trusted-artifact-signer --debug charts/trusted-artifact-signer -n sigstore --create-namespace --values -
```

### Monitor Sigstore Components with Grafana

Expand Down
30 changes: 30 additions & 0 deletions docs/quick-start-with-sigstore-issuer.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
## Quick Start with Sigstore Public OIDC Issuer

1. Use the installer's `install` command to install the required signing keys and root certificate for keyless signing and install the sigstore stack.

To build the installer

```
go build -C tas-installer -o ../tas-install
```

The installer expects a `kubeconfig` file at `$HOME/.kube/config`,, or that the flag `--kubeconfig /path/to/kubeconfig` is provided.
By default, the fulcio server is configured to use the upstream public OIDC issuer at `oauth2.sigstore.dev/auth`. An interactive browser
based flow in which you will authenticate with Google, GitHub, or MicroSoft will be initiated when signing artifacts..

First, the user is prompted for information in order to create rekor and fulcio signing keys as well as the fulcio root certificate.
Then, the Trusted Artifact Signer resources will be created. The stack is ready to use when all jobs have been completed. The job
in the `tuf-system` namespace will be the last to complete, and can take several minutes.

```shell
./tas-install install
```

Watch `oc get jobs -A` and when the `tuf-system` job is complete, the TAS stack should be ready to sign & verify artifacts.

Once complete, move to the [Sign & Verify document](sign-verify.md) to test the Sigstore stack.

If there is already a helm release `trusted-artifact-signer` installed, the command `./tas-install install` will perform an upgrade.
In this case, it will reuse the signing keys and certificate secrets from the connected cluster's `fulcio-system` and `rekor-system`
namespaces.

51 changes: 51 additions & 0 deletions docs/tas-install.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
## Trusted Artifact Signer Installer

The `tas-install` command is experimental. To build it, run the following from the repository root.

```
go build -C tas-installer -o ../tas-install
```

### Install

```
$ ./tas-install install -h
Installs Trusted Artifact Signer (TAS) on a Kubernetes cluster.
This command performs a series of actions:
1. Initializes the Kubernetes client to interact with your cluster
2. Sets up necessary certificates
3. Configures secrets
4. Deploys TAS to openshift
Usage:
tas-installer install [flags]
Flags:
--chart-location string /local/path/to/chart or oci://registry/repo location of Helm chart (default "./charts/trusted-artifact-signer")
--chart-version string Version of the Helm chart (default "0.1.29")
-h, --help help for install
--oidc-client-id string Specify the OIDC client ID
--oidc-issuer-url string Specify the OIDC issuer URL e.g for keycloak: https://[keycloak-domain]/auth/realms/[realm-name]
--oidc-type string Specify the OIDC type
--values string path to custom values file for chart configuration
Global Flags:
--kubeconfig string Specify the kubeconfig path (default "$HOME/.kube/config")
```

### Uninstall

```
$ ./tas-install uninstall -h
Removes installation of Trusted Artifact Signer (TAS) on a Kubernetes cluster.
Usage:
tas-installer uninstall [flags]
Flags:
-h, --help help for uninstall
Global Flags:
--kubeconfig string Specify the kubeconfig path (default "$HOME/.kube/config")
```
2 changes: 1 addition & 1 deletion tas-installer/cmd/install.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ func installTas(tasNamespace string) error {
}

func init() {
installCmd.PersistentFlags().StringVar(&helmChartVersion, "chart-version", "0.1.29", "Version of the Helm chart")
installCmd.PersistentFlags().StringVar(&helmChartVersion, "chart-version", "0.1.30", "Version of the Helm chart")
installCmd.PersistentFlags().StringVar(&helmChartLocation, "chart-location", "./charts/trusted-artifact-signer", "/local/path/to/chart or oci://registry/repo location of Helm chart")
installCmd.PersistentFlags().StringVar(&helmValuesFile, "values", "", "path to custom values file for chart configuration")
installCmd.PersistentFlags().StringVar(&oidcConfig.IssuerURL, "oidc-issuer-url", "", "Specify the OIDC issuer URL e.g for keycloak: https://[keycloak-domain]/auth/realms/[realm-name]")
Expand Down

0 comments on commit fed7a21

Please sign in to comment.