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 <moyerm@vmware.com>

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" >}})!

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 . | kapp deploy --app pinniped-concierge --file -`
-
-     `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 -`
 
 ## Next steps
 

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.
 <!-- TODO: link to support matrix -->
 
+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 . | kapp deploy --app pinniped-supervisor --file -`
-
-     `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 -`
 
 ## Next steps
 

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 \
+   kubectl apply --context kind-pinniped-concierge \
-     --context kind-pinniped-concierge \
+     -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-concierge-crds.yaml
-     -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.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`.
 

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

site/themes/pinniped/layouts/shortcodes/buttonlink.html

@@ -1,2 +1,2 @@
-{{- $href := .Get "href" -}}
+{{- $filename := .Get "filename" -}}
-<div class="button"><a href="{{ $href }}" class="button secondary">{{.Inner}}</a></div>
+<div class="button"><a href="https://get.pinniped.dev/{{ .Site.Params.latest_version }}/{{ $filename }}" class="button secondary">{{.Inner}}</a></div>