Skip to content

Backport kontena/kontena#2504 node token docs #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SpComb wants to merge 7 commits into
base: master
Choose a base branch
from
Open

Backport kontena/kontena#2504 node token docs #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6489f1b
doc node token agent envs
Aug 31, 2017
ee8b863
fix grid env docs
Aug 31, 2017
98fe3e7
document new kontena node commands
Aug 31, 2017
7fdb03c
fix heading levels
Aug 31, 2017
771e8b8
will -> would
Aug 31, 2017
43446d5
Show Kontena Node Configuration
Sep 1, 2017
fbe74df
/etc/kontena-agent.env
Sep 1, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions advanced/grids.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,12 +98,14 @@ Show audit logs.
$ kontena grid audit-log
```

## Show Kontena Platform Grid Environment Details
## Show Kontena Node Configuration

Outputs currently used Kontena Platform Grid environment variables that can be used to configure Kontena CLI.
Generate the [`/etc/kontena-agent.env` environment variables](../references/environment-variables#kontena-agent) required when manually provisioning nodes using grid tokens:
Copy link
Contributor Author

@SpComb SpComb Sep 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This links to the "Kontena Agent" section on the environment variables reference. Do we also want to avoid the mention of /etc/kontena-agent.env here?


```
$ kontena grid env
KONTENA_URI=ws://192.168.66.1:9292/
KONTENA_TOKEN=yempbjWHbZLhc66gB0mAFXKS8HzS/daDwCfnHC+UfrJo5wkhQ6hpr8XKY5nUdH+h6CH81Y9bQIc4IgTcEEjQCQ==
```

## Show Kontena Platform Grid Cloud-Config
Expand Down
7 changes: 5 additions & 2 deletions references/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,11 @@

## Kontena Agent

- `KONTENA_URI`: Kontena Master websocket uri (required)
- `KONTENA_TOKEN`: Kontena Grid token (required)
The `KONTENA_URI` and either of `KONTENA_TOKEN` or `KONTENA_NODE_TOKEN` is required.

- `KONTENA_URI`: Kontena Master websocket uri, `ws://...` or `wss://...` (required)
- `KONTENA_TOKEN`: Kontena [Grid token](../using-kontena/nodes.md#grid-token)
- `KONTENA_NODE_TOKEN`: Kontena [Node token](../using-kontena/nodes.md#node-token)
- `KONTENA_PEER_INTERFACE`: network interface for peer/private communication (default: eth1)
- `KONTENA_PUBLIC_IP`: specify node public ip, overrides default resolving
- `KONTENA_PRIVATE_IP`: specify node private ip, overrides default resolving
Expand Down
48 changes: 46 additions & 2 deletions using-kontena/nodes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,29 @@ In this chapter, we'll discover how to manage, operate and monitor Kontena Nodes

Please see the [Add Kontena Nodes](install-nodes/README.md) documentation to learn more.

## Create Kontena Nodes

Create a new Kontena Node for manual provisioning:
Copy link
Contributor Author

@SpComb SpComb Sep 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Create Kontena Node stuff should be moved to install-nodes/README.md and/or one of its sub documents

So the using-kontena/nodes.md should not have any mention of kontena node create?

Writing up the detailed docs in install-nodes/README.md is still WIP, I can move this to that branch.


```
$ kontena node create core-03
[done] Creating core-03 node
```

The server will generate a random node token by default. Use `--token` to supply a pre-generated node token.

The new node must be provisioned using the `kontena node env` configuration.

## List Kontena Nodes

The command that may be used for listing all Kontena Nodes in a Kontena Platform.

```
$ kontena node list
NAME VERSION STATUS INITIAL LABELS
⊛ core-01 1.4.0 online 1 / 1 provider=vagrant
⊛ core-02 1.4.0 online - provider=vagrant
⊝ core-03 1.4.0 offline - -
```

## Show Kontena Node Information
Expand All @@ -33,6 +50,18 @@ The command that may be used for inspecting Kontena Node information.
$ kontena node show <NODE_ID>
```

## Show Kontena Node Configuration

Generate the [`/etc/kontena-agent.env` environment variables](../references/environment-variables#kontena-agent) required when manually provisioning nodes using node tokens:

```
$ kontena node env core-03
KONTENA_URI=ws://192.168.66.1:9292/
KONTENA_NODE_TOKEN=yempbjWHbZLhc66gB0mAFXKS8HzS/daDwCfnHC+UfrJo5wkhQ6hpr8XKY5nUdH+h6CH81Y9bQIc4IgTcEEjQCQ==
```

See [`kontena grid env`](./platform.md#show-kontena-node-configuration) or [`kontena node reset-token`](#reset-a-kontena-node-token) if the node was not created using `kontena node create`.

## Update Kontena Node Information

```
Expand All @@ -47,15 +76,30 @@ The command that may be used for connecting to Kontena Node via SSH.
$ kontena node ssh <NODE_ID>
```

## Reset a Kontena Node Token

The `kontena node reset-token` command can be used to replace a compromised node token, upgrade a node that was originally provisioned using a grid token, or revert a node to using a grid token:

```
$ kontena node reset-token <NODE_ID>
```

Resetting the token of an online Kontena Node will force the agent to disconnect. The agent will not be able to reconnect until the the node is reconfigured using the new `kontena node env` values.

The `kontena node reset-token` command can also be used to upgrade a node provisioned using a grid token. The node must be reconfigured using the new `kontena node env` configuration before it will be able to reconnect. The `kontena node reset-token --clear-token` command can be used to revert back to the grid token.


## Remove a Kontena Node

In order to remove a Kontena Node, it must be terminated first. Once terminated, it may be removed. Only `offline` Kontena Nodes may be removed.
The `kontena node remove` command can be used to remove a node that is being decomissioned:

```
$ kontena node remove <NODE_ID>
```

If you are using the Kontena CLI built-in provision tool, you can terminate Kontena Node using the `kontena <provider> node terminate` command. Alternatively, power off / terminate the Kontena Node machine from any infrastructure you are using and wait for the machine to become offline before removing them.
If the node was provisioned using the Kontena CLI built-in provisioning tool, you can terminate the host machine using the `kontena <provider> node terminate` command. This will also remove the Kontena Node. If the host machine has already been terminated, then the `kontena node remove` command can be used to forget the terminated node.

If the node was provisioned with a node token, then the `kontena node remove` command can also be used to invalidate the node token, forcing the agent to disconnect if it is still connected. Nodes provisioned using grid tokens cannot be removed if they are still online, because the agent would simply reconnect and the node would quickly re-appear.
Copy link
Contributor Author

@SpComb SpComb Sep 1, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove Kontena Node - Is there additional value of having longer story?

There are now two kinds of nodes: those with grid tokens and those with node tokens. They behave differently in terms of kontena node remove.

The kontena <provider> node terminate is still the main preferred thing to use. Removing an online node provisioned using a node token will still leave the machine running. That implies something like you losing access to that node and wanting to kick it out of your grid ASAP.

Should we drop support for removing online nodes connected using node tokens, to simplify the docs? You could still use kontena node reset-token to force it to disconnect , and then remove it after waiting for it to go offline.


**IMPORTANT!** If you remove a Kontena Node that has `stateful` Kontena Service instances deployed, those Kontena Service instances will be re-scheduled for the next Kontena Service deploy and lose their state.

Expand Down
6 changes: 4 additions & 2 deletions using-kontena/platform.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,12 +169,14 @@ Show audit logs.
$ kontena grid audit-log
```

## Show Kontena Platform Grid Environment Details
## Show Kontena Node Configuration

Outputs currently used Kontena Platform Grid environment variables that can be used to configure Kontena CLI.
Generate the [`/etc/kontena-agent.env` environment variables](../references/environment-variables#kontena-agent) required when manually provisioning nodes using grid tokens:

```
$ kontena grid env
KONTENA_URI=ws://192.168.66.1:9292/
KONTENA_TOKEN=yempbjWHbZLhc66gB0mAFXKS8HzS/daDwCfnHC+UfrJo5wkhQ6hpr8XKY5nUdH+h6CH81Y9bQIc4IgTcEEjQCQ==
```

## Show Kontena Platform Grid Cloud-Config
Expand Down