Skip to content
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.

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

replace Vault with OpenBao in documentation #44

Merged
merged 2 commits into from
Jan 22, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
42 changes: 21 additions & 21 deletions website/content/docs/agent-and-proxy/agent/apiproxy.mdx
Original file line number Diff line number Diff line change
@@ -1,62 +1,62 @@
---
layout: docs
page_title: Vault Agent API Proxy
page_title: OpenBao Agent API Proxy
description: >-
Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
for Vault's API.
OpenBao Agent's API Proxy functionality allows you to use OpenBao Agent's API as a proxy
for OpenBao's API.
---

# Vault agent API proxy
# OpenBao agent API proxy

Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
for Vault's API.
OpenBao Agent's API Proxy functionality allows you to use OpenBao Agent's API as a proxy
for OpenBao's API.

~> Note: This functionality will be deprecated in a future release. Please
switch to using [Vault Proxy](/vault/docs/agent-and-proxy/proxy) for API proxying purposes, instead.
switch to using [OpenBao Proxy](/vault/docs/agent-and-proxy/proxy) for API proxying purposes, instead.
JanMa marked this conversation as resolved.
Show resolved Hide resolved

## Functionality

The [`listener` stanza](/vault/docs/agent-and-proxy/agent#listener-stanza) for Vault Agent configures a listener for Vault Agent. If
its `role` is not set to `metrics_only`, it will act as a proxy for the Vault server that
has been configured in the [`vault` stanza](/vault/docs/agent-and-proxy/agent#vault-stanza) of Vault Agent. This enables access to the Vault
The [`listener` stanza](/vault/docs/agent-and-proxy/agent#listener-stanza) for OpenBao Agent configures a listener for OpenBao Agent. If
its `role` is not set to `metrics_only`, it will act as a proxy for the OpenBao server that
has been configured in the [`vault` stanza](/vault/docs/agent-and-proxy/agent#vault-stanza) of OpenBao Agent. This enables access to the OpenBao
API from the Agent API, and can be configured to optionally allow or force the automatic use of
the Auto-Auth token for these requests, as described below.

If a `listener` has been configured alongside a `cache` stanza, the API Proxy will
first attempt to utilize the cache subsystem for qualifying requests, before forwarding the
request to Vault. See the [caching docs](/vault/docs/agent-and-proxy/agent/caching) for more information on caching.
request to OpenBao. See the [caching docs](/vault/docs/agent-and-proxy/agent/caching) for more information on caching.

## Using Auto-Auth token

Vault Agent allows for easy authentication to Vault in a wide variety of
OpenBao Agent allows for easy authentication to OpenBao in a wide variety of
environments using [Auto-Auth](/vault/docs/agent-and-proxy/autoauth). By setting the
`use_auto_auth_token` (see below) configuration, clients will not be required
to provide a Vault token to the requests made to the Agent. When this
to provide a OpenBao token to the requests made to the Agent. When this
configuration is set, if the request doesn't already bear a token, then the
auto-auth token will be used to forward the request to the Vault server. This
auto-auth token will be used to forward the request to the OpenBao server. This
configuration will be overridden if the request already has a token attached,
in which case, the token present in the request will be used to forward the
request to the Vault server.
request to the OpenBao server.

## Forcing Auto-Auth token

Vault Agent can be configured to force the use of the auto-auth token by using
OpenBao Agent can be configured to force the use of the auto-auth token by using
the value `force` for the `use_auto_auth_token` option. This configuration
overrides the default behavior described above in [Using Auto-Auth
Token](/vault/docs/agent-and-proxy/agent/apiproxy#using-auto-auth-token), and instead ignores any
existing Vault token in the request and instead uses the auto-auth token.
existing OpenBao token in the request and instead uses the auto-auth token.


## Configuration (`api_proxy`)

The top level `api_proxy` block has the following configuration entries:

- `use_auto_auth_token` `(bool/string: false)` - If set, the requests made to Agent
without a Vault token will be forwarded to the Vault server with the
without a OpenBao token will be forwarded to the OpenBao server with the
auto-auth token attached. If the requests already bear a token, this
configuration will be overridden and the token in the request will be used to
forward the request to the Vault server. If set to `"force"` Agent will use the
auto-auth token, overwriting the attached Vault token if set.
forward the request to the OpenBao server. If set to `"force"` Agent will use the
auto-auth token, overwriting the attached OpenBao token if set.

The following two `api_proxy` options are only useful when making requests to a Vault
Enterprise cluster, and are documented as part of its
Expand All @@ -75,7 +75,7 @@ Here is an example of a `listener` configuration alongside `api_proxy` configura
and enforce consistency.

```hcl
# Other Vault agent configuration blocks
# Other OpenBao agent configuration blocks
# ...

api_proxy {
Expand Down
34 changes: 17 additions & 17 deletions website/content/docs/agent-and-proxy/agent/caching/index.mdx
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
---
layout: docs
page_title: Vault Agent Caching
page_title: OpenBao Agent Caching
description: |-
Vault Agent Caching allows client-side caching of responses containing newly
OpenBao Agent Caching allows client-side caching of responses containing newly
created tokens and responses containing leased secrets generated off of these
newly created tokens.
---

# Vault agent caching
# OpenBao agent caching

Vault Agent Caching allows client-side caching of responses containing newly
OpenBao Agent Caching allows client-side caching of responses containing newly
created tokens and responses containing leased secrets generated off of these
newly created tokens. The renewals of the cached tokens and leases are also
managed by the agent.

-> **Note:** Vault Agent Caching works best with servers/clusters that are
-> **Note:** OpenBao Agent Caching works best with servers/clusters that are
running on Vault 1.1 and above due to changes that were introduced
alongside this feature, such as the exposure of the `orphan` field in token
creation responses.
Expand All @@ -38,10 +38,10 @@ specific scenarios.

## Persistent cache

Vault Agent can restore tokens and leases from a persistent cache file created
by a previous Vault Agent process.
OpenBao Agent can restore tokens and leases from a persistent cache file created
by a previous OpenBao Agent process.

Refer to the [Vault Agent Persistent
Refer to the [OpenBao Agent Persistent
Caching](/vault/docs/agent-and-proxy/agent/caching/persistent-caches) page for more information on
this functionality.

Expand All @@ -53,15 +53,15 @@ TTL or if the renewals result in errors.

Agent does some best-effort cache evictions by observing specific request types
and response codes. For example, if a token revocation request is made via the
agent and if the forwarded request to the Vault server succeeds, then agent
agent and if the forwarded request to the OpenBao server succeeds, then agent
evicts all the cache entries associated with the revoked token. Similarly, any
lease revocation operation will also be intercepted by the agent and the
respective cache entries will be evicted.

Note that while agent evicts the cache entries upon secret expirations and upon
intercepting revocation requests, it is still possible for the agent to be
completely unaware of the revocations that happen through direct client
interactions with the Vault server. This could potentially lead to stale cache
interactions with the OpenBao server. This could potentially lead to stale cache
entries. For managing the stale entries in the cache, an endpoint
`/agent/v1/cache-clear`(see below) is made available to manually evict cache
entries based on some of the query criteria used for indexing the cache entries.
Expand All @@ -86,14 +86,14 @@ the caching functionality is built upon.
## Renewal management

The tokens and leases are renewed by the agent using the secret renewer that is
made available via the Vault server's [Go
made available via the OpenBao server's [Go
API](https://godoc.org/github.com/lf-edge/openbao/api#Renewer). Agent performs
all operations in memory and does not persist anything to storage. This means
that when the agent is shut down, all the renewal operations are immediately
terminated and there is no way for agent to resume renewals after the fact.
Note that shutting down the agent does not indicate revocations of the secrets,
instead it only means that renewal responsibility for all the valid unrevoked
secrets are no longer performed by the Vault agent.
secrets are no longer performed by the OpenBao agent.

### Agent CLI

Expand Down Expand Up @@ -190,7 +190,7 @@ These are common configuration values that live within the `persist` block:
is not deleted. Defaults to `false`.

- `exit_on_err` `(bool: optional)` - When set to true, if any errors occur during
a persistent cache restore, Vault Agent will exit with an error. Defaults to `true`.
a persistent cache restore, OpenBao Agent will exit with an error. Defaults to `true`.

- `service_account_token_file` `(string: optional)` - When `type` is set to `kubernetes`,
this configures the path on disk where the Kubernetes service account token can be found.
Expand Down Expand Up @@ -232,13 +232,13 @@ Here is an example of a cache configuration with the optional `persist` block,
alongside a regular listener, and a listener that only serves metrics.

```hcl
# Other Vault agent configuration blocks
# Other OpenBao agent configuration blocks
# ...

cache {
persist = {
type = "kubernetes"
path = "/vault/agent-cache/"
path = "/openbao/agent-cache/"
JanMa marked this conversation as resolved.
Show resolved Hide resolved
keep_after_import = true
exit_on_err = true
service_account_token_file = "/tmp/serviceaccount/token"
Expand All @@ -259,6 +259,6 @@ listener "tcp" {

## Tutorial

Refer to the [Vault Agent
Refer to the [OpenBao Agent
Caching](/vault/tutorials/vault-agent/agent-caching)
tutorial to learn how to use the Vault Agent to increase the availability of tokens and secrets to clients using its Caching function.
tutorial to learn how to use the OpenBao Agent to increase the availability of tokens and secrets to clients using its Caching function.
Original file line number Diff line number Diff line change
@@ -1,32 +1,32 @@
---
layout: docs
page_title: Vault Agent Persistent Caching
description: Vault Agent Caching
page_title: OpenBao Agent Persistent Caching
description: OpenBao Agent Caching
---

# Vault agent persistent caching
# OpenBao agent persistent caching

Vault Agent can restore tokens and leases from a persistent cache file created
by a previous Vault Agent process. The persistent cache is a BoltDB file that
OpenBao Agent can restore tokens and leases from a persistent cache file created
by a previous OpenBao Agent process. The persistent cache is a BoltDB file that
includes tuples encrypted by a generated encryption key. The encrypted tuples
include the Vault token used to retrieve secrets, leases for tokens/secrets, and
include the OpenBao token used to retrieve secrets, leases for tokens/secrets, and
secret values.

-> **Note:** Vault Agent Persistent Caching will only restore _leased_
-> **Note:** OpenBao Agent Persistent Caching will only restore _leased_
secrets. Secrets that are not renewable, such as KV v2, will not be persisted.

In order to use Vault Agent persistent cache, auto-auth must be used. If the
In order to use OpenBao Agent persistent cache, auto-auth must be used. If the
auto-auth token has expired by the time the cache is restored, the cache will
be invalidated and secrets will need to be re-fetched from Vault.
be invalidated and secrets will need to be re-fetched from OpenBao.

If Vault Agent templating is enabled alongside of the persistent cache, Vault
If OpenBao Agent templating is enabled alongside of the persistent cache, OpenBao
Agent will automatically route templating requests through the cache. This
ensures template requests are cached and restored properly.

-> **Note** Vault Agent persistent cache is currently supported only in a
-> **Note** OpenBao Agent persistent cache is currently supported only in a
Kubernetes environment.

## Vault agent persistent cache types
## OpenBao agent persistent cache types

Please see the sidebar for available types and their usage/configuration.

Expand All @@ -35,12 +35,12 @@ Please see the sidebar for available types and their usage/configuration.
Here is an example of a persistent cache configuration.

```hcl
# Other Vault agent configuration blocks
# Other OpenBao agent configuration blocks
# ...

cache {
persist "kubernetes" {
path = "/vault/agent-cache"
path = "/openbao/agent-cache"
}
}
```
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
---
layout: docs
page_title: Kubernetes - Vault Agent Persistent Cache
description: Kubernetes Persistent Cache for Vault Agent Caching
page_title: Kubernetes - OpenBao Agent Persistent Cache
description: Kubernetes Persistent Cache for OpenBao Agent Caching
---

# Vault agent kubernetes persistent cache
# OpenBao agent kubernetes persistent cache

When `kubernetes` is configured for the persistent cache type, Vault Agent will optimize the
When `kubernetes` is configured for the persistent cache type, OpenBao Agent will optimize the
persistent cache specifically for Kubernetes. This type of persistent cache requires a Kubernetes
service account token. The service account token is used during encryption and decryption of the
persistent cache as an additional integrity check.

The Vault Agent persistent cache file in Kubernetes should only be used for handing off Vault tokens
and leases between initialization and sidecar Vault Agent containers. This cache file should be shared
using a memory volume between the Vault Agent containers.
The OpenBao Agent persistent cache file in Kubernetes should only be used for handing off OpenBao tokens
and leases between initialization and sidecar OpenBao Agent containers. This cache file should be shared
using a memory volume between the OpenBao Agent containers.

If the Vault Agent Injector for Kubernetes is being used, the persistent cache is automatically configured
If the OpenBao Agent Injector for Kubernetes is being used, the persistent cache is automatically configured
JanMa marked this conversation as resolved.
Show resolved Hide resolved
and used if the annotation [`vault.hashicorp.com/agent-cache-enable: true`](/vault/docs/platform/k8s/injector/annotations#vault-hashicorp-com-agent-cache-enable) is set.

## Configuration
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@
layout: docs
page_title: agent generate-config - Command
description: |-
Generates a simple Vault Agent configuration file from the given parameters.
Generates a simple OpenBao Agent configuration file from the given parameters.
---

# agent generate-config

Generates a simple Vault Agent configuration file from the given parameters.
Generates a simple OpenBao Agent configuration file from the given parameters.

Currently, the only supported configuration type is `env-template`, which
helps you generate a configuration file with environment variable templates
for running Vault Agent in
for running OpenBao Agent in
[process supervisor](/vault/docs/agent-and-proxy/agent/process-supervisor)
mode.

Expand All @@ -24,7 +24,7 @@ only [kv-v1](/vault/docs/secrets/kv/kv-v1) and
[kv-v2](/vault/docs/secrets/kv/kv-v2) paths are supported.

The command specified in the `-exec` option will be used to generate an
`exec` entry, which will tell Vault Agent which child process to run.
`exec` entry, which will tell OpenBao Agent which child process to run.

In addition to the `env_template` entries, the command generates an `auto_auth`
section with `token_file` authentication method. While this method is very
Expand All @@ -40,13 +40,13 @@ unless a path is specified as an argument.
Before generating a configuration file, let's insert a secret `foo`:

```shell-session
$ vault kv put -mount=secret foo user="admin" password="s3cr3t"
$ bao kv put -mount=secret foo user="admin" password="s3cr3t"
```

Generate an agent configuration file which will reference `secret/foo`:

```shell-session
$ vault agent generate-config \
$ bao agent generate-config \
-type="env-template" \
-exec="./my-app arg1 arg2" \
-namespace="my/ns/" \
Expand Down Expand Up @@ -123,6 +123,6 @@ flags](/vault/docs/commands) included in all commands.

## Tutorial

Refer to the [Vault Agent - secrets as environment
Refer to the [OpenBao Agent - secrets as environment
variables](/vault/tutorials/vault-agent/agent-env-vars) tutorial for an
end-to-end example.
end-to-end example.
Loading
Loading