Skip to content

Commit 5f059bf

Browse files
dkennetzoracledkennetzoracle
authored
Secrets usage (#96)
* Updating documentation for secrets. * NIM Secrets. * Added example of using secrets with huggingface. * Added container registry docs. * Removed unnecessary link. * Added recipe_container_secret.
1 parent 7438bd0 commit 5f059bf

18 files changed

+762
-0
lines changed

‎docs/api_documentation.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,25 @@ There are 3 blueprints that we are providing out of the box. Following are examp
122122

123123
`GET /deployment_logs/`
124124

125+
## List all secrets
126+
127+
`GET /secrets/`
128+
129+
## List namespaced secrets
130+
131+
`GET /secrets/?namespace={namespace}`
132+
133+
## Get secret by name
134+
135+
`GET /secrets/{name}/`
136+
137+
## Create, Update, Delete secrets
138+
139+
`POST /secrets/{payload}`
140+
141+
Details in [secrets sample blueprints](./secrets/README.md)
142+
143+
125144
## Frequently Asked Questions
126145

127146
**Can I deploy custom models?**

‎docs/secrets/README.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Secrets in AI Blueprints
2+
3+
Secrets enable users to store confidential access in kubernetes without needing to frequently expose them in blueprints, leading to more secure deployments.
4+
5+
Currently, two types of secrets are supported:
6+
7+
- `opaque`: general secrets such as API keys, huggingface tokens, which allow users to provide any key / value pair for access
8+
- `container_registry`: structured secrets for accessing private container registries for private containers to deploy to blueprints, such as private OCI container registries, NVIDIA NGC for NIMs, or Docker.
9+
10+
### Listing, Creating, Updating, and Deleting Secrets with the `/secrets` API endpoint
11+
12+
This API allows users to list, create, update, or delete stored secrets in blueprints. The [schema](./secrest_schema.json) is included for reference.
13+
14+
To see valid API calls for `GET` requests, visit [api docs](../api_documentation.md#list-all-secrets).
15+
16+
`POST` requests to create, update, or delete secrets are described in the table below. Post requests can perform batch operations, with statuses reported for each.
17+
18+
1. Trying to `create` a token which exists will fail
19+
2. Trying to `update` a token which doesn't exist will fail
20+
3. Trying to `delete` a token which doesn't exist will fail
21+
22+
For `opaque` secrets, multiple data keys can exist within a single secret under distinct `key:value` pairs as will be shown in the example table below.
23+
24+
| Mode | Secret Type | Example Payload | Response |
25+
| :--: | :---------: | :-------------: | :------: |
26+
| `create` | `opaque` | [create-opaque-secret](./example_opaque_create.json) | `400 BAD REQUEST` for fail or `200 OK` for success |
27+
| `update` | `opaque` | [update-opaque-secret](./example_opaque_update.json) | `400 BAD REQUEST` for fail or `200 OK` for success |
28+
| `delete` | `opaque` | [delete-opaque-secret](./example_opaque_delete.json) | `400 BAD REQUEST` for fail or `200 OK` for success |
29+
| `create` | `container_registry` | [create-registry-secret](./example_registry_create.json) | `400 BAD REQUEST` for fail or `200 OK` for success |
30+
| `update` | `container_registry` | [update-registry-secret](./example_registry_update.json) | `400 BAD REQUEST` for fail or `200 OK` for success |
31+
| `delete` | `container_registry` | [delete-registry-secret](./example_registry_delete.json) | `400 BAD REQUEST` for fail or `200 OK` for success |
32+
33+
### Using secrets in Blueprints
34+
35+
Secrets leverage two different blueprint recipe keys depending on the type:
36+
37+
- `recipe_container_secret_name` (string) -> The name of the container_registry secret where the credentials were stored (e.g "iad-creds" in the [create-registry-secret](./example_registry_create.json))
38+
- `recipe_environment_secrets` (array[object]) -> An array of objects containing the 3 fields which stores the value of the secret key in the container at the specified environment variable name:
39+
- `"envvar_name"`: the name of the environment variable the secret should map to
40+
- `"secret_name"`: the name of the secret which contains the key:value pair
41+
- `"secret_key"`: the key containing the value you want to use
42+
43+
As an example using a huggingface token, you would store the secret like:
44+
45+
```json
46+
{
47+
"secrets_payload": [
48+
{
49+
"name": "hf-secret",
50+
"action": "create",
51+
"type": "opaque",
52+
"data": {
53+
"hf-token": "hf_...<example-token>..."
54+
}
55+
}
56+
]
57+
}
58+
```
59+
60+
Then, to use it in a blueprint as an environment variable and an argument:
61+
```json
62+
...
63+
"recipe_environment_secrets": [
64+
{
65+
"envvar_name": "HF_TOKEN",
66+
"secret_name": "hf-secret",
67+
"secret_key": "hf-token"
68+
}
69+
],
70+
"recipe_container_command_args": [
71+
"--token",
72+
"$(HF_TOKEN)",
73+
...
74+
]
75+
...
76+
```
77+
78+
### Secrets workflows
79+
80+
The following four examples show common workflows utilizing secrets in different ways:
81+
82+
- [Using Secrets with NVIDIA NIMs](./using_secrets_with_nvidia_nim.md)
83+
- [Using Secrets with Huggingface](./using_secrets_with_huggingface.md)
84+
- [Using Secrets with Container Registries](./using_secrets_with_container_registry.md)
85+

‎docs/secrets/container_registry_secret.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"secrets_payload": [
3+
{
4+
"name": "iad-creds",
5+
"action": "create",
6+
"type": "container_registry",
7+
"data": {
8+
"registry_server": "iad.ocir.io",
9+
"username": "iad.ocir.io/[email protected]",
10+
"password": "auth-token-here",
11+
"email": "[email protected]"
12+
}
13+
}
14+
]
15+
}

‎docs/secrets/example_opaque_create.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"secrets_payload": [
3+
{
4+
"name": "app-config",
5+
"action": "create",
6+
"type": "opaque",
7+
"data": {
8+
"database_url": "postgresql://new-host:5432/mydb",
9+
"api_key": "new-api-key-456"
10+
}
11+
}
12+
]
13+
}

‎docs/secrets/example_opaque_delete.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"secrets_payload": [
3+
{
4+
"name": "app-config",
5+
"action": "delete",
6+
"type": "opaque"
7+
}
8+
]
9+
}

‎docs/secrets/example_opaque_update.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"secrets_payload": [
3+
{
4+
"name": "app-config",
5+
"action": "update",
6+
"type": "opaque",
7+
"data": {
8+
"database_url": "postgresql://new-host:5432/mydb",
9+
"api_key": "new-api-key-457"
10+
}
11+
}
12+
]
13+
}
14+

‎docs/secrets/example_registry_create.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"secrets_payload": [
3+
{
4+
"name": "iad-creds",
5+
"action": "create",
6+
"type": "container_registry",
7+
"data": {
8+
"registry_server": "iad.ocir.io",
9+
"username": "mytenancy/[email protected]",
10+
"password": "auth-token-here",
11+
"email": "[email protected]"
12+
}
13+
},
14+
{
15+
"name": "phx-creds",
16+
"action": "create",
17+
"type": "container_registry",
18+
"data": {
19+
"registry_server": "phx.ocir.io",
20+
"username": "mytenancy/[email protected]",
21+
"password": "auth-token-here",
22+
"email":"[email protected]"
23+
}
24+
}
25+
]
26+
}

‎docs/secrets/example_registry_delete.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"secrets_payload": [
3+
{
4+
"name": "iad-creds",
5+
"action": "delete"
6+
},
7+
{
8+
"name": "phx-creds",
9+
"action": "delete"
10+
}
11+
]
12+
}

‎docs/secrets/example_registry_update.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"secrets_payload": [
3+
{
4+
"name": "iad-creds",
5+
"action": "create",
6+
"type": "container_registry",
7+
"data": {
8+
"registry_server": "iad.ocir.io",
9+
"username": "mytenancy/[email protected]",
10+
"password": "auth-token-here2",
11+
"email": "[email protected]"
12+
}
13+
},
14+
{
15+
"name": "phx-creds",
16+
"action": "create",
17+
"type": "container_registry",
18+
"data": {
19+
"registry_server": "phx.ocir.io",
20+
"username": "mytenancy/[email protected]",
21+
"password": "auth-token-here2",
22+
"email":"[email protected]"
23+
}
24+
}
25+
]
26+
}

‎docs/secrets/hf-token-secret.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"secrets_payload": [
3+
{
4+
"name": "hf-secret",
5+
"action": "create",
6+
"type": "opaque",
7+
"data": {
8+
"hf-token": "hf_...<example-token>..."
9+
}
10+
}
11+
]
12+
}

0 commit comments

Comments
 (0)