Merge pull request #755 from mattmoyer/update-installation-docs

Update installation documentation

site/config.yaml

@@ -7,6 +7,7 @@ params:
   github_url: "https://github.com/vmware-tanzu/pinniped"
   slack_url: "https://kubernetes.slack.com/messages/pinniped"
   community_url: "https://go.pinniped.dev/community"
+  latest_version: v0.9.2
 pygmentsCodefences: true
 pygmentsStyle: "pygments"
 markup:

site/content/docs/howto/configure-supervisor.md

@@ -49,7 +49,7 @@ The most common ways are:
    and the service.
 
 For either of the first two options, if you installed using `ytt` then you can use
-the related `service_*` options from [deploy/supervisor/values.yml](values.yaml) to create a Service.
+the related `service_*` options from [deploy/supervisor/values.yml](https://github.com/vmware-tanzu/pinniped/blob/main/deploy/supervisor/values.yaml) to create a Service.
 If you installed using `install-supervisor.yaml` then you can create
 the Service separately after installing the Supervisor app. There is no `Ingress` included in the `ytt` templates,
 so if you choose to use an Ingress then you'll need to create that separately after installing the Supervisor app.

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,18 +44,16 @@ 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 v0.9.2 on Linux/amd64:
+For example, to install {{< latestversion >}} on Linux/amd64:
 
 ```sh
-curl -Lso pinniped https://get.pinniped.dev/v0.9.2/pinniped-cli-linux-amd64 \
+curl -Lso pinniped https://get.pinniped.dev/{{< latestversion >}}/pinniped-cli-linux-amd64 \
   && chmod +x pinniped \
   && sudo mv pinniped /usr/local/bin/pinniped
 ```
 
-*Replace v0.9.2 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`
+   - `kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/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/v0.9.2/install-pinniped-concierge.yaml`
-
-      *Replace v0.9.2 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:
 
@@ -43,30 +51,25 @@ 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. `v0.9.2`.
+1. Checkout your preferred version tag, e.g. `{{< latestversion >}}`.
 
-   - `git checkout v0.9.2`
+   - `git checkout {{< latestversion >}}`
-
-     *Replace v0.9.2 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. `v0.9.2`. *Replace v0.9.2 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.
 
+     For example, you can change the number of Concierge pods by setting `replicas` or apply custom annotations to the impersonation proxy service using `impersonation_proxy_spec`.
+
 1. Render templated YAML manifests:
 
    - `ytt --file .`
 
 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`
+   - `kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/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/v0.9.2/install-pinniped-supervisor.yaml`
-
-     *Replace v0.9.2 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. `v0.9.2`.
+1. Checkout your preferred version tag, e.g. `{{< latestversion >}}`:
 
-    - `git checkout v0.9.2`
+    - `git checkout {{< latestversion >}}`
-
-      *Replace v0.9.2 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. `v0.9.2`. *Replace v0.9.2 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 `v0.9.2`.
-
 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>

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

@@ -0,0 +1 @@
+{{ .Site.Params.latest_version }}