mirror of
https://github.com/pomerium/pomerium.git
synced 2025-06-02 19:04:14 +02:00
docs: add installation section (#1223)
This commit is contained in:
Travis Groth
GitHub
parent
1cafba18a5
commit
4976fe3824
5 changed files with 113 additions and 45 deletions
|
|
@ -9,6 +9,109 @@ description: >-
|
|||
|
||||
## Overview
|
||||
|
||||
Pomerium is shipped in multiple formats and architectures to suit a variety of deployment patterns. There are two binaries:
|
||||
|
||||
`pomerium` is the server component. It is a monolithic binary that can perform the function of any [services mode](/reference/#service-mode), depending on configuration.
|
||||
|
||||
`pomerium-cli` is the user component. It is a similarly monolithic binary handling user facing capabilities such as pomerium service account creation and authentication helper functions.
|
||||
|
||||
## Pomerium
|
||||
|
||||
## Pomerium CLI
|
||||
- Supported Operating Systems: `linux`, `darwin`
|
||||
- Supported Architectures: `amd64`, `arm64`
|
||||
|
||||
Pomerium releases include both the `pomerium` and `pomerium-cli` binaries.
|
||||
|
||||
### Binaries
|
||||
|
||||
Official binaries can be found on our [GitHub Releases](https://github.com/pomerium/pomerium/releases) page.
|
||||
|
||||
```shell
|
||||
ARCH=[your arch]
|
||||
OS=[your os]
|
||||
VERSION=[desired version]
|
||||
curl -L https://github.com/pomerium/pomerium/releases/download/${VERSION}/pomerium-${OS}-${ARCH}.tar.gz \
|
||||
| tar -z -x
|
||||
```
|
||||
|
||||
### Docker Image
|
||||
|
||||
Pomerium utilizes a [minimal](https://github.com/GoogleContainerTools/distroless) [docker container](https://www.docker.com/resources/what-container). You can find Pomerium's images on [dockerhub](https://hub.docker.com/r/pomerium/pomerium). Pomerium can be pulled in several flavors and architectures.
|
||||
|
||||
- `:vX.Y.Z`: which will pull the a [specific tagged release](https://github.com/pomerium/pomerium/tags).
|
||||
|
||||
```bash
|
||||
$ docker run pomerium/pomerium:v0.1.0 --version
|
||||
v0.1.0+53bfa4e
|
||||
```
|
||||
|
||||
- `:latest`: which will pull the [most recent tagged release](https://github.com/pomerium/pomerium/releases).
|
||||
|
||||
```bash
|
||||
$ docker pull pomerium/pomerium:latest && docker run pomerium/pomerium:latest --version
|
||||
v0.2.0+87e214b
|
||||
```
|
||||
|
||||
- `:master` : which will pull an image in sync with git's [master](https://github.com/pomerium/pomerium/tree/master) branch.
|
||||
|
||||
```shell
|
||||
docker pull pomerium/pomerium:latest
|
||||
```
|
||||
|
||||
### Helm
|
||||
|
||||
Pomerium maintains a [helm](https://helm.sh) chart for easy Kubernetes deployment with best practices [https://helm.pomerium.io/](https://helm.pomerium.io/)
|
||||
|
||||
```shell
|
||||
helm repo add pomerium https://helm.pomerium.io
|
||||
helm install pomerium/pomerium
|
||||
```
|
||||
|
||||
See the [README](https://github.com/pomerium/pomerium-helm/blob/master/charts/pomerium/README.md) for up to date install options.
|
||||
|
||||
### Source
|
||||
|
||||
::: tip
|
||||
Officially supported build platforms are limited by envoy proxy. If you have an
|
||||
enoy binary for your platform in your path at start time, `pomerium` should function correctly.
|
||||
:::
|
||||
|
||||
```shell
|
||||
git clone git@github.com:pomerium/pomerium.git
|
||||
cd pomerium
|
||||
make
|
||||
./bin/pomerium --version
|
||||
```
|
||||
|
||||
## Pomerium CLI
|
||||
|
||||
- Supported Operating Systems: `linux`, `darwin`, `windows`, `freebsd`
|
||||
- Supported Architectures: `amd64`, `arm64`, `armv6`, `armv7`
|
||||
|
||||
### Binaries
|
||||
|
||||
Official binaries can be found on our [GitHub Releases](https://github.com/pomerium/pomerium/releases) page.
|
||||
|
||||
```shell
|
||||
ARCH=[your arch]
|
||||
OS=[your os]
|
||||
VERSION=[desired version]
|
||||
curl -L https://github.com/pomerium/pomerium/releases/download/${VERSION}/pomerium-cli-${OS}-${ARCH}.tar.gz \
|
||||
| tar -z -x
|
||||
```
|
||||
|
||||
### Homebrew
|
||||
|
||||
```shell
|
||||
brew tap pomerium/tap
|
||||
brew install pomerium-cli
|
||||
```
|
||||
|
||||
### Source
|
||||
|
||||
```shell
|
||||
git clone git@github.com:pomerium/pomerium.git
|
||||
cd pomerium
|
||||
make
|
||||
./bin/pomerium-cli --help
|
||||
```
|
||||
|
|
@ -19,12 +19,12 @@ Pomerium can be used to:
|
|||
- enforce **dynamic access policy** based on **context**, **identity**, and **device state**.
|
||||
- aggregate access logs and telemetry data.
|
||||
- perform delegated user authorization for service-based authorization systems:
|
||||
- [Istio](/guides/istio.html)
|
||||
- [Google Cloud](/guides/cloud-run.html)
|
||||
- [Istio](/guides/istio.md)
|
||||
- [Google Cloud](/guides/cloud-run.md)
|
||||
- provide unified identity attestation for upstream services:
|
||||
- [Kubernetes](/guides/kubernetes.html)
|
||||
- [Grafana](/guides/istio.html#pomerium-configuration)
|
||||
- [Custom applications](/docs/topics/getting-users-identity.html)
|
||||
- [Kubernetes](/guides/kubernetes.md)
|
||||
- [Grafana](/guides/istio.md#pomerium-configuration)
|
||||
- [Custom applications](/docs/topics/getting-users-identity.md)
|
||||
- provide a **VPN alternative**.
|
||||
|
||||
## Architecture
|
||||
|
|
|
|||
|
|
@ -1,40 +1,5 @@
|
|||
# Releases
|
||||
|
||||
## Binaries
|
||||
|
||||
Official binaries for OSX, Windows, and Linux can be found on our [Github Releases](https://github.com/pomerium/pomerium/releases) page.
|
||||
|
||||
## Docker
|
||||
|
||||
Pomerium is also distributed as a [minimal](https://github.com/GoogleContainerTools/distroless) [docker container](https://www.docker.com/resources/what-container). You can find Pomerium's images on [dockerhub](https://hub.docker.com/r/pomerium/pomerium). Pomerium can be pulled in several flavors and architectures.
|
||||
|
||||
- `:vX.Y.Z`: which will pull the a [specific tagged release](https://github.com/pomerium/pomerium/tags).
|
||||
|
||||
```bash
|
||||
$ docker run pomerium/pomerium:v0.1.0 --version
|
||||
v0.1.0+53bfa4e
|
||||
```
|
||||
|
||||
- `:latest`: which will pull the [most recent tagged release](https://github.com/pomerium/pomerium/releases).
|
||||
|
||||
```bash
|
||||
$ docker pull pomerium/pomerium:latest && docker run pomerium/pomerium:latest --version
|
||||
v0.2.0+87e214b
|
||||
```
|
||||
|
||||
- `:master` : which will pull an image in sync with git's [master](https://github.com/pomerium/pomerium/tree/master) branch.
|
||||
|
||||
## Source
|
||||
|
||||
If you'd like to run Pomerium on an [operating system or architecture](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63) not officially released by Pomerium, or simply prefer to compile from source, you can do so by checking out the latest code and compiling as follows.
|
||||
|
||||
```bash
|
||||
git clone git@github.com:pomerium/pomerium.git
|
||||
cd pomerium
|
||||
make
|
||||
./bin/pomerium --version
|
||||
```
|
||||
|
||||
## Release Cycle
|
||||
|
||||
The current release cycle is aligned on a monthly basis. Pre-`1.0.0` we target a `MINOR` release on or around the **first day of each month**. We try to hit the targets as closely as possible, while still delivering a quality release.
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ Building on top of a standard Kubernetes and Pomerium deployment:
|
|||
1. Pomerium is given access to a Kubernetes service account with [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) permissions
|
||||
2. A [policy route](/reference/#policy) is created for the API server and [configured](/reference/#kubernetes-service-account-token) to use the service account token
|
||||
3. Kubernetes RoleBindings operate against IdP Users and Group subjects
|
||||
4. Users access the protected cluster through their standard tools, using [pomerium-cli](/docs/installation.md#pomerium-client) as an auth provider in `~/.kube/config`
|
||||
4. Users access the protected cluster through their standard tools, using [pomerium-cli](/docs/installation.md#pomerium-cli) as an auth provider in `~/.kube/config`
|
||||
5. Pomerium authorizes requests and passes the user identity to the API server for fine grained RBAC
|
||||
|
||||
## Kubeconfig Setup
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ In dedicated service mode, you have the opportunity to scale the components of P
|
|||
|
||||
All of Pomerium's components are designed to be stateless, and may all be scaled horizontally or vertically. In general, horizontal scaling is recommended. Vertical scaling will lead to diminished returns after ~8 vCPUs.
|
||||
|
||||
The Cache service, which is responsible for session and identity related data, must be [configured for external persistence](/docs/topics/data-storage.html) to be fully stateless.
|
||||
The Cache service, which is responsible for session and identity related data, must be [configured for external persistence](/docs/topics/data-storage.md) to be fully stateless.
|
||||
|
||||
### Proxy
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ The Cache service is responsible for background identity data retrieval and stor
|
|||
The Cache service does not require significant resources, as it provides streaming updates of state changes to the Authorize service. There will be utilization spikes when Authorize services are restarted and perform an initial synchronization. Add resources if running many Authorize services and performing restarts in large batches. In many deployments, 2 replicas of Cache is enough to provide resilient service.
|
||||
|
||||
::: warning
|
||||
In a production configuration, Cache CPU/IO utilization also translates to IO load on the [underlying storage system](/docs/topics/data-storage.html). Ensure it is scaled accordingly!
|
||||
In a production configuration, Cache CPU/IO utilization also translates to IO load on the [underlying storage system](/docs/topics/data-storage.md). Ensure it is scaled accordingly!
|
||||
:::
|
||||
|
||||
## Load Balancing
|
||||
|
|
@ -99,7 +99,7 @@ Regardless of the service mode, it is recommended you run 2+ instances of Pomeri
|
|||
Ensure that you have enough spare capacity to handle the scope of your failure domains.
|
||||
|
||||
::: warning
|
||||
Multiple replicas of Cache or all-in-one service are only supported with [external storage](/docs/topics/data-storage.html) configured
|
||||
Multiple replicas of Cache or all-in-one service are only supported with [external storage](/docs/topics/data-storage.md) configured
|
||||
:::
|
||||
|
||||
## SSL/TLS Certificates
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue