From fd5ed2e5da67d436818dc0d799a26676e780af48 Mon Sep 17 00:00:00 2001 From: Matt Moyer Date: Wed, 28 Jul 2021 15:02:23 -0500 Subject: [PATCH] Rework "install" sections of our docs. - Remove all the "latest" links and replace them with our new shortcode so they point at the latest release in a more explicit way. This also eliminates one of the sections in our Concierge and Supervisor install guides, since you're always installing a specific version. - Provide instructions for installing with both kapp (one step) and kubectl (two steps for the Concierge). - Minor wording changes. Mainly we are now a bit less verbose about reminding people they can choose a different version (once per page instead of in each step). - When we give an example `kapp deploy` command, don't suggest `--yes` and `--diff-changes`. Users can still use these but it seems overly verbose for an example command. Signed-off-by: Matt Moyer --- site/content/docs/howto/install-cli.md | 10 ++--- site/content/docs/howto/install-concierge.md | 45 ++++++++++--------- site/content/docs/howto/install-supervisor.md | 36 +++++++-------- .../concierge-and-supervisor-demo.md | 12 +++-- .../docs/tutorials/concierge-only-demo.md | 12 ++--- .../layouts/shortcodes/buttonlink.html | 4 +- 6 files changed, 59 insertions(+), 60 deletions(-) diff --git a/site/content/docs/howto/install-cli.md b/site/content/docs/howto/install-cli.md index c9ec8b7e..aa5e388c 100644 --- a/site/content/docs/howto/install-cli.md +++ b/site/content/docs/howto/install-cli.md @@ -23,11 +23,11 @@ Use [Homebrew](https://brew.sh/) to install from the Pinniped [tap](https://gith Find the appropriate binary for your platform from the [latest release](https://github.com/vmware-tanzu/pinniped/releases/latest): -{{< buttonlink href="https://get.pinniped.dev/latest/pinniped-cli-darwin-amd64" >}}Download for macOS/amd64{{< buttonicon "download.png" >}}{{< /buttonlink >}} +{{< buttonlink filename="pinniped-cli-darwin-amd64" >}}Download {{< latestversion >}} for macOS/amd64{{< buttonicon "download.png" >}}{{< /buttonlink >}} -{{< buttonlink href="https://get.pinniped.dev/latest/pinniped-cli-linux-amd64" >}}Download for Linux/amd64{{< buttonicon "download.png" >}}{{< /buttonlink >}} +{{< buttonlink filename="pinniped-cli-linux-amd64" >}}Download {{< latestversion >}} for Linux/amd64{{< buttonicon "download.png" >}}{{< /buttonlink >}} -{{< buttonlink href="https://get.pinniped.dev/latest/pinniped-cli-windows-amd64.exe" >}}Download for Windows/amd64{{< buttonicon "download.png" >}}{{< /buttonlink >}} +{{< buttonlink filename="pinniped-cli-windows-amd64.exe" >}}Download {{< latestversion >}} for Windows/amd64{{< buttonicon "download.png" >}}{{< /buttonlink >}} You should put the command-line tool somewhere on your `$PATH`, such as `/usr/local/bin` on macOS/Linux. You'll also need to mark the file as executable. @@ -44,7 +44,7 @@ Click Open to allow the command to proceed. ## Install a specific version via script -Choose your preferred [release](https://github.com/vmware-tanzu/pinniped/releases) version number and use it to replace the version number in the URL below. +Choose your preferred [release](https://github.com/vmware-tanzu/pinniped/releases) and use it to replace the version number in the URL below. For example, to install {{< latestversion >}} on Linux/amd64: @@ -54,8 +54,6 @@ curl -Lso pinniped https://get.pinniped.dev/{{< latestversion >}}/pinniped-cli-l && sudo mv pinniped /usr/local/bin/pinniped ``` -*Replace {{< latestversion >}} with your preferred version number.* - ## Next steps Next, [install the Supervisor]({{< ref "install-supervisor.md" >}}) and/or [install the Concierge]({{< ref "install-concierge.md" >}})! diff --git a/site/content/docs/howto/install-concierge.md b/site/content/docs/howto/install-concierge.md index b22a645e..a2786ba1 100644 --- a/site/content/docs/howto/install-concierge.md +++ b/site/content/docs/howto/install-concierge.md @@ -12,29 +12,37 @@ menu: This guide shows you how to install the Pinniped Concierge. You should have a [supported Kubernetes cluster]({{< ref "../reference/supported-clusters" >}}). +In the examples below, you can replace *{{< latestversion >}}* with your preferred version number. +You can find a list of Pinniped releases [on GitHub](https://github.com/vmware-tanzu/pinniped/releases). + ## With default options +**Warning:** the default Concierge configuration may create a public LoadBalancer Service on your cluster if that is the default on your cloud provider. +If you'd prefer to customize the annotations or load balancer IP address, see the "With custom options" section below. + +### Using kapp + +1. Install the latest version of the Concierge into the `pinniped-concierge` namespace with default options using [kapp](https://carvel.dev/kapp/): + + - `kapp deploy --app pinniped-concierge--file https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-concierge.yaml` + +### Using kubectl + +1. Install the latest version of the Concierge CustomResourceDefinitions: + + - `kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-concierge-crds.yaml` + + This step is required so kubectl can validate the custom resources deployed in the next step. + 1. Install the latest version of the Concierge into the `pinniped-concierge` namespace with default options: - - `kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-concierge.yaml` - -Warning: the default configuration may create a public LoadBalancer Service on your cluster. - -## With specific version and default options - -1. Choose your preferred [release](https://github.com/vmware-tanzu/pinniped/releases) version number and use it to replace the version number in the URL below. - -1. Install the Concierge into the `pinniped-concierge` namespace with default options: - - `kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-concierge.yaml` - *Replace {{< latestversion >}} with your preferred version number.* - ## With custom options Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/) as a templating system. -1. Install the `ytt` command-line tool using the instructions from the [Carvel documentation](https://carvel.dev/#whole-suite). +1. Install the `ytt` and `kapp` command-line tools using the instructions from the [Carvel documentation](https://carvel.dev/#whole-suite). 1. Clone the Pinniped GitHub repository and visit the `deploy/concierge` directory: @@ -47,12 +55,10 @@ Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/) - `git checkout {{< latestversion >}}` - *Replace {{< latestversion >}} with your preferred version number.* - 1. Customize configuration parameters: - Edit `values.yaml` with your custom values. - - Change the `image_tag` value to match your preferred version tag, e.g. `{{< latestversion >}}`. *Replace {{< latestversion >}} with your preferred version number.* + - Change the `image_tag` value to match your preferred version tag, e.g. `{{< latestversion >}}`. - See the [default values](http://github.com/vmware-tanzu/pinniped/tree/main/deploy/concierge/values.yaml) for documentation about individual configuration parameters. 1. Render templated YAML manifests: @@ -61,12 +67,7 @@ Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/) 1. Deploy the templated YAML manifests: - - *If you're using `kubectl`:* - - `ytt --file . | kubectl apply -f -` - - *If you're using [`kapp` from Carvel](https://carvel.dev/kapp/):* - - `ytt --file . | kapp deploy --yes --app pinniped-concierge --diff-changes --file -` + - `ytt --file . | kapp deploy --app pinniped-concierge --file -` ## Next steps diff --git a/site/content/docs/howto/install-supervisor.md b/site/content/docs/howto/install-supervisor.md index 5d869507..d2ca21e0 100644 --- a/site/content/docs/howto/install-supervisor.md +++ b/site/content/docs/howto/install-supervisor.md @@ -13,27 +13,28 @@ This guide shows you how to install the Pinniped Supervisor, which allows seamle You should have a supported Kubernetes cluster with working HTTPS ingress capabilities. +In the examples below, you can replace *{{< latestversion >}}* with your preferred version number. +You can find a list of Pinniped releases [on GitHub](https://github.com/vmware-tanzu/pinniped/releases). + ## With default options +### Using kapp + +1. Install the latest version of the Supervisor into the `pinniped-supervisor` namespace with default options using [kapp](https://carvel.dev/kapp/): + + - `kapp deploy --app pinniped-supervisor --file https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-supervisor.yaml` + +### Using kubectl + 1. Install the latest version of the Supervisor into the `pinniped-supervisor` namespace with default options: - - `kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-supervisor.yaml` - -## With specific version and default options - -1. Choose your preferred [release](https://github.com/vmware-tanzu/pinniped/releases) version number and use it to replace the version number in the URL below. - -1. Install the Supervisor into the `pinniped-supervisor` namespace with default options: - - `kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-supervisor.yaml` - *Replace {{< latestversion >}} with your preferred version number.* - ## With custom options Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/) as a templating system. -1. Install the `ytt` command-line tool using the instructions from the [Carvel documentation](https://carvel.dev/#whole-suite). +1. Install the `ytt` and `kapp` command-line tools using the instructions from the [Carvel documentation](https://carvel.dev/#whole-suite). 1. Clone the Pinniped GitHub repository and visit the `deploy/supervisor` directory: @@ -42,16 +43,14 @@ Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/) 1. Decide which release version you would like to install. All release versions are [listed on GitHub](https://github.com/vmware-tanzu/pinniped/releases). -1. Checkout your preferred version tag, e.g. `{{< latestversion >}}`. +1. Checkout your preferred version tag, e.g. `{{< latestversion >}}`: - `git checkout {{< latestversion >}}` - *Replace {{< latestversion >}} with your preferred version number.* - 1. Customize configuration parameters: - Edit `values.yaml` with your custom values. - - Change the `image_tag` value to match your preferred version tag, e.g. `{{< latestversion >}}`. *Replace {{< latestversion >}} with your preferred version number.* + - Change the `image_tag` value to match your preferred version tag, e.g. `{{< latestversion >}}`. - See the [default values](http://github.com/vmware-tanzu/pinniped/tree/main/deploy/supervisor/values.yaml) for documentation about individual configuration parameters. 1. Render templated YAML manifests: @@ -60,12 +59,7 @@ Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/) 1. Deploy the templated YAML manifests: - - *If you're using `kubectl`:* - - `ytt --file . | kubectl apply -f -` - - *If you're using [`kapp` from Carvel](https://carvel.dev/kapp/):* - - `ytt --file . | kapp deploy --yes --app pinniped-supervisor --diff-changes --file -` + `ytt --file . | kapp deploy --app pinniped-supervisor --file -` ## Next steps diff --git a/site/content/docs/tutorials/concierge-and-supervisor-demo.md b/site/content/docs/tutorials/concierge-and-supervisor-demo.md index 3d2ae8c2..8dcda1f5 100644 --- a/site/content/docs/tutorials/concierge-and-supervisor-demo.md +++ b/site/content/docs/tutorials/concierge-and-supervisor-demo.md @@ -144,12 +144,16 @@ to authenticate federated identities from the Supervisor. 1. Deploy the Pinniped Concierge. ```sh - kubectl apply \ - --context kind-pinniped-concierge \ - -f https://get.pinniped.dev/latest/install-pinniped-concierge.yaml + kubectl apply --context kind-pinniped-concierge \ + -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-concierge-crds.yaml + kubectl apply --context kind-pinniped-concierge \ + -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-concierge.yaml ``` - The `install-pinniped-concierge.yaml` file includes the default deployment options. + The `install-pinniped-concierge-crds.yaml` file contains the Concierge CustomResourceDefinitions. + These define the custom APIs that you use to configure and interact with the Concierge. + + The `install-pinniped-concierge.yaml` file includes the rest of the Concierge resources with default deployment options. If you would prefer to customize the available options, please see the [Concierge installation guide]({{< ref "../howto/install-concierge" >}}) for instructions on how to deploy using `ytt`. diff --git a/site/content/docs/tutorials/concierge-only-demo.md b/site/content/docs/tutorials/concierge-only-demo.md index 7ef3502d..de8eb88e 100644 --- a/site/content/docs/tutorials/concierge-only-demo.md +++ b/site/content/docs/tutorials/concierge-only-demo.md @@ -71,7 +71,7 @@ as the authenticator. an authenticator that works with your real identity provider, and therefore would not need to deploy or configure local-user-authenticator. ```sh - kubectl apply -f https://get.pinniped.dev/latest/install-local-user-authenticator.yaml + kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/install-local-user-authenticator.yaml ``` The `install-local-user-authenticator.yaml` file includes the default deployment options. @@ -79,8 +79,6 @@ as the authenticator. see [deploy/local-user-authenticator/README.md](https://github.com/vmware-tanzu/pinniped/blob/main/deploy/local-user-authenticator/README.md) for instructions on how to deploy using `ytt`. - If you prefer to install a specific version, replace `latest` in the URL with the version number such as `{{< latestversion >}}`. - 1. Create a test user named `pinny-the-seal` in the local-user-authenticator namespace. ```sh @@ -101,10 +99,14 @@ as the authenticator. 1. Deploy the Pinniped Concierge. ```sh - kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-concierge.yaml + kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-concierge-crds.yaml + kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-concierge.yaml ``` - The `install-pinniped-concierge.yaml` file includes the default deployment options. + The `install-pinniped-concierge-crds.yaml` file contains the Concierge CustomResourceDefinitions. + These define the custom APIs that you use to configure and interact with the Concierge. + + The `install-pinniped-concierge.yaml` file includes the rest of the Concierge resources with default deployment options. If you would prefer to customize the available options, please see the [Concierge installation guide]({{< ref "../howto/install-concierge" >}}) for instructions on how to deploy using `ytt`. diff --git a/site/themes/pinniped/layouts/shortcodes/buttonlink.html b/site/themes/pinniped/layouts/shortcodes/buttonlink.html index 7895fc5e..ea46e14a 100644 --- a/site/themes/pinniped/layouts/shortcodes/buttonlink.html +++ b/site/themes/pinniped/layouts/shortcodes/buttonlink.html @@ -1,2 +1,2 @@ -{{- $href := .Get "href" -}} -
{{.Inner}}
\ No newline at end of file +{{- $filename := .Get "filename" -}} +
{{.Inner}}
\ No newline at end of file