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>
This commit is contained in:
Matt Moyer 2021-07-28 15:02:23 -05:00
parent ca82609d1a
commit fd5ed2e5da
No known key found for this signature in database
GPG Key ID: EAE88AD172C5AE2D
6 changed files with 59 additions and 60 deletions

View File

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

View File

@ -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

View File

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

View File

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

View File

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

View File

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