gsadmin/ziti
1
0
Fork 0
mirror of https://github.com/openziti/ziti.git synced 2026-10-12 07:18:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

update docs to cover cases where token is sought in env var and stdin

Browse Source
This commit is contained in:
Kenneth Bingham
2022-05-19 18:34:31 -04:00
parent e7b385ae94
commit 0819affd35
1 changed files with 60 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ziti-tunnel/docker/README.md
+60 -30
View File
@@ -10,7 +10,11 @@ when the one-time enrollment token is consumed.
## Variables
- `NF_REG_NAME`: The name of the identity that ziti-tunnel will assume.
- `NF_REG_NAME`: Required - file basename of the enroll token JWT file or identity config JSON file that ziti-tunnel will use
- `NF_REG_TOKEN`: Optional - one-time enrollment token to use instead of `${NF_REG_NAME}.jwt`
If `${NF_REG_NAME}.jwt` does not exist and `NF_REG_TOKEN` is not defined the enroller will try to get the token from
stdin if it is not a TTY.
## Volumes
@@ -26,53 +30,72 @@ following directories:
- `/netfoundry`: This would be used when running in the Docker engine (or IoT Edge).
This could be a bind mount or a docker volume.
- `/enrollment-token`: Alternative mount point for the enrollment token only.
- `/var/run/secrets/netfoundry.io/enrollment-token`: When running in Kubernetes,
the enrollment token should be mounted as a secret at this mount point.
# Examples
## Examples
## Docker
### Docker
The ziti-tunnel image can be used in a vanilla Docker environment.
# enroll with token from inherited env var and run hosting-only mode without any nameserver or IP routes
$ mkdir ./ziti_id
$ export NF_REG_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbSI6Im90dCIsImV4cCI6MTY1MzE2NzcwOCwiaXNzIjoiaHR0cHM6Ly81MGEyMDc4Zi01MGQyLTRhZTAtYWI4Ny0wYTdjMjM1OWVjOTYucHJvZHVjdGlvbi5uZXRmb3VuZHJ5LmlvOjQ0MyIsImp0aSI6IjFiMjJkMzc2LTMzMWItNDMxNS1iZTFiLWJkOTUzYThiYWM4ZiIsInN1YiI6InRGLnZnLjdwM1kifQ.TWbk3-kjBRKwQCXMoD93sXtyQhZOMZ1iJzV73Sqft-cEOkV2kjbA4TBRwl0nuLPCdJqkhPl9Yc1WG7YaYWYXV4ghE1Hk0Gta_HlpWdNjNlB1cVrzMyxaoCXhaX5xqGnwDuqfOK7q6DItuNsKouM2G6KKZvhGOacax6TvP-sunsxFz6AdYQJizNBoL5fJ14r1_O6yczGd5GSd8x9-eP5rNMQuRdUtiu69b-rEu1gO2SXVTrADTD5p8sP9khbT_eQzIDD9jgagXoJJvOKTVdsUAWS7YKfk1On0BpxNvv30bQ6eAkliwU7GTXDR2IPW-blZYt1Wtf3sgeuTDCCtVO_7gjSn7WM7YJqpsB72V-43Xz8I7LCDa0u48baSmmpPDUSphIBDa_nksPZk8jfwx4pHoHYbSbD4r47Af_9P-JUQRT8hzNuvktG56kmcqVCfEZHT-4xgK0Lvxxp4mzqdcNyCB0VwC6kdk7OlxwqmftDWrJhNuxKMy2MtyTjG0mwHxt4P0y_fZo1ZYJZU5AzvxrE9OLTjsQ4nV5NliJ3Qxaw_taCaIWxn98BeiHfAiIc3EL7bWGjAfXz-XWvWG8-AcCmK-cxIj7Pvj0U7lIWH7bVcRmVVc0fQnXdACkeQe7ixWr4IopV5YJ607zm6Qk_am_MrERla6xyXblvroWIITN2aEUk
$ docker run --rm \
-v $(pwd)/ziti_id:/netfoundry \
-e NF_REG_NAME=ziti_id \
-e NF_REG_TOKEN \
openziti/ziti-tunnel:latest
# enroll with a JWT file and run a transparent proxy with built-in nameserver
$ mkdir ./ziti_id
$ cp ~/Downloads/ziti_id.jwt ./ziti_id
$ docker run -t --network=host --cap-add=NET_ADMIN \
-v $(pwd)/ziti_id:/netfoundry \
-e NF_REG_NAME=ziti_id \
netfoundry/ziti-tunnel:0.5.7-2546
openziti/ziti-tunnel:latest
Notes:
- The container that runs ziti-tunnel will only be able to intercept traffic for
other processes within the same container, unless the container uses the "host"
network mode.
- The container requires NET_ADMIN capability to create iptables rules.
- The `NF_REG_NAME` environment variable must be set to the name of the ziti
identity that ziti-tunnel will assume when connecting to the controller.
- The container that runs ziti-tunnel will only be able to intercept traffic for other processes within the same
container, unless the container uses the "host" network mode.
- No special network mode or additional capabilities are required when running `ziti-tunnel host`, which is the
hosting-only run mode without any built-in nameserver or IP routers or iptables rules
- The container requires NET_ADMIN capability to create iptables rules in the host network when running in the default
mode `ziti-tunnel tproxy` (implied by `ziti-tunnel run`).
- The `NF_REG_NAME` environment variable must be set to the name of the ziti identity that ziti-tunnel will assume when
connecting to the controller.
- The "/netfoundry" directory must be mounted on its own volume.
- The one-time enrollment token "/netfoundry/${NF_REG_NAME}.jwt" must exist when
the container is started for the first time. This is the JWT that was downloaded
from the controller when the Ziti identity was created.
- "/netfoundry/${NF_REG_NAME}.json" is created when the identity is enrolled.
The "/netfoundry" volume must be persistent (that is, ${NF_REG_NAME}.json must
endure container restarts), since the enrollment token is only valid for one
enrollment.
- The one-time enrollment token "/netfoundry/${NF_REG_NAME}.jwt" is sought by the enroller when the container is
started for the first time. This is the JWT that was downloaded from the controller when the Ziti identity was
created.
- If the JWT file is not found in one of the well-known directories then the token is subsequently sought from the
env var `NF_REG_TOKEN`, then stdin.
- "/netfoundry/${NF_REG_NAME}.json" is created when the identity is enrolled. The "/netfoundry" volume must be
persistent (that is, ${NF_REG_NAME}.json must endure container restarts), since the enrollment token is only valid
for one enrollment.
## Docker Compose
### Docker Compose
This example uses Compose to store in a file the Docker `build` and `run` parameters for several modes of operation of `ziti-tunnel`.
This example uses Compose to store in a file the Docker `build` and `run` parameters for several modes of operation of `ziti-tunnel`.
### Docker Compose Setup
#### Docker Compose Setup
1. Install Docker Engine.
2. `docker-compose` is a utility you can install with the Python Package Index (PyPi) e.g. `pip install --upgrade docker-compose`.
3. Save your Ziti identity enrollment token e.g. `my-ziti-identity-file.jwt` in the same directory as the file named `docker-compose.yml`. Your identity will be enrolled the first time you run the container, and the permanent identity file will be saved e.g. `my-ziti-identity-file.json`.
4. You may change `ZITI_VERSION` to [another release version from our ziti-release repository](https://netfoundry.jfrog.io/ui/repos/simple/Properties/ziti-release%2Fziti-tunnel%2Famd64%2Flinux%2F0.15.2%2Fziti-tunnel.tar.gz).
2. `docker-compose` is a utility you can install with the Python Package Index (PyPi) e.g. `pip install --upgrade
docker-compose`.
3. Save your Ziti identity enrollment token e.g. `my-ziti-identity-file.jwt` in the same directory as the file named
`docker-compose.yml`. Your identity will be enrolled the first time you run the container, and the permanent
identity file will be saved e.g. `my-ziti-identity-file.json`.
4. You may change `ZITI_VERSION` to [another release version from our ziti-release
repository](https://netfoundry.jfrog.io/ui/repos/simple/Properties/ziti-release%2Fziti-tunnel%2Famd64%2Flinux%2F0.15.2%2Fziti-tunnel.tar.gz).
#### Docker Transparent Proxy for Linux
### Docker Transparent Proxy for Linux
1. Modify "ziti-tproxy" under "services" in the file named `docker-compose.yml` in this Git repo, optionally overriding the default value of `command` to pass additional parameters to `ziti-tunnel`.
1. Modify "ziti-tproxy" under "services" in the file named `docker-compose.yml` in this Git repo, optionally overriding
the default value of `command` to pass additional parameters to `ziti-tunnel`.
```yaml
version: "3.3"
@@ -90,6 +113,7 @@ services:
- NET_ADMIN
environment:
- NF_REG_NAME
- NF_REG_TOKEN
# command: run --resolver udp://127.0.0.123:53
# command: run --resolver none
```
@@ -98,8 +122,11 @@ services:
This will cause the container to configure the Linux host to transparently proxy any domain names or IP addresses that match a Ziti service.
### Docker Proxy or MacOS or Windows
1. Modify "ziti-proxy" under "services" in the file named `docker-compose.yml` in this Git repo. Change the service name(s) and port number(s) to suit your actual services. You must align the mapped ports under `ports` with the bound ports in the `command`.
#### Docker Proxy or MacOS or Windows
1. Modify "ziti-proxy" under "services" in the file named `docker-compose.yml` in this Git repo. Change the service
name(s) and port number(s) to suit your actual services. You must align the mapped ports under `ports` with the
bound ports in the `command`.
```yaml
version: "3.3"
@@ -114,6 +141,7 @@ services:
- .:/netfoundry
environment:
- NF_REG_NAME
- NF_REG_TOKEN
ports:
- "8888:8888"
- "9999:9999"
@@ -126,9 +154,10 @@ services:
NF_REG_NAME=my-ziti-identity-file docker-compose up --build ziti-proxy
```
This will cause the container to listen on the mapped port(s) and proxy any received traffic to the Ziti service that is bound to that port.
This will cause the container to listen on the mapped port(s) and proxy any received traffic to the Ziti service that
are bound to that port.
## Kubernetes
### Kubernetes
The ziti-tunnel image can be used in Kubernetes either as a sidecar, which would
intercept packets only from other containers in the pod definition or as a dedicated
@@ -200,7 +229,7 @@ The following example manifest shows how to run ziti-tunnel as a sidecar:
secretName: tunnel-sidecar.jwt
```
## Azure IoT Hub
### Azure IoT Hub
This image can be used to run a module on an Azure IoT runtime.
@@ -208,6 +237,7 @@ This image can be used to run a module on an Azure IoT runtime.
$ cat module.json
```json
{
"modulesContent": {