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

Update installation documentation
This commit is contained in:
Matt Moyer 2021-07-29 17:54:23 -05:00 committed by GitHub
commit 0ab8e14e4a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 71 additions and 68 deletions

View File

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

View File

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

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

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/v0.9.2/install-pinniped-concierge.yaml`
*Replace v0.9.2 with your preferred version number.*
- `kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-concierge.yaml`
## 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`
*Replace v0.9.2 with your preferred version number.*
- `git checkout {{< latestversion >}}`
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 . | 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/v0.9.2/install-pinniped-supervisor.yaml`
*Replace v0.9.2 with your preferred version number.*
- `kubectl apply -f https://get.pinniped.dev/{{< latestversion >}}/install-pinniped-supervisor.yaml`
## 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`
*Replace v0.9.2 with your preferred version number.*
- `git checkout {{< latestversion >}}`
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 . | 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 `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`.

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>

View File

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