# Secrets

> Octelium documentation. Canonical page: <https://octelium.com/docs/octelium/latest/management/core/secret>.

As in Kubernetes, Octelium has a dedicated *Secret* type for storing sensitive data such as API tokens and passwords, which can be used and referenced by other *Cluster* resources via the *Secret*'s name to avoid storing sensitive data along with other *Cluster* configurations that can be stored in Git repositories, for example.

*Secrets* are used by various other *Cluster* resources such as *Services*, and *IdentityProviders*. For example, *Services* use *Secrets* to provide secretless access. You can read more about secretless access [here](https://octelium.com/docs/octelium/latest/management/core/service/secretless.md).

## Creating a Secret

You can create a *Secret* via the `octeliumctl create secret` command using one of the following ways:

### Value via Prompt

You can insert your *Secret* value directly via prompt as follows:

```bash
octeliumctl create secret apikey1
    Enter the secret: <SECRET_VALUE>
```

### From File

You can also create a *Secret* from the content of a file as follows:

```bash
octeliumctl create secret aws-ssh-pk --file /PATH/TO/SSH/PRIVATE_KEY
```

### TLS Certificate

You can create a *Secret* from a TLS certificate using the PEM file paths of the certificate chain and its corresponding private key. Such *Secrets* are typically useful for use cases like a *Service* using the *Secret* as a client certificate to connect to the *Service*'s upstream, which is protected by mTLS (read more [here](https://octelium.com/docs/octelium/latest/management/core/service/secretless.md#mutual-tls)).

```bash
octeliumctl create secret mtls-k8s-01 --cert /PATH/TO/CERTIFICATE_CHAIN.PEM --cert-key /PATH/TO/CERTIFICATE_PRIVATE_KEY.PEM
```

## Listing Secrets

You can list the *Cluster*'s *Secrets* (read more about listing resources [here](https://octelium.com/docs/octelium/latest/management/core/overview.md#listing-resources)) as follows:

```bash
octeliumctl get secret
# Or simply
octeliumctl get sec

# Show a certain Secret
octeliumctl get sec <NAME>
```

> **Note:**
>
> It is important to understand that the *Cluster* does not currently expose the *Secret* data itself via the API, and consequently the `octeliumctl` CLI, but only keeps the *Secret*'s actual sensitive value internally. In other
> words, the `octeliumctl get secret` command only exposes the *Secret* resource
> without its `data` field that actually contains the *Secret*'s sensitive data.

## Deleting a Secret

You can also delete a *Secret* as follows:

```bash
octeliumctl delete secret <SECRET_NAME>
# OR
octeliumctl del sec <SECRET_NAME>
```

## Using the Declarative Approach

You can actually use `octeliumctl apply` with *Secrets* as well via the `--include-secret` flag. This assumes that you have a way to store such YAML files securely (e.g. encrypted or in a secrets manager), as opposed to pushing them to Git repositories like ordinary resource configurations.. Here is an example:

```yaml
kind: Secret
metadata:
  name: my-secret
spec: {}
data:
  value: TOP_SECRET_VALUE
```

And you can simply apply your changes as follows:

```bash
octeliumctl apply --include-secret /PATH/TO/SECRETS
```

## Secret Storage

Just like in Kubernetes, the Octelium *Cluster*, by default, stores a *Secret*'s data in plaintext like any other *Cluster* resource. However, Octelium gives you the ability to develop your own encryption-at-rest method according to your requirements by providing a gRPC interface (see [here](https://github.com/octelium/octelium/tree/main/apis/cluster/csecretmanv1)) where you can intercept *Secret* Create/Get/Update/List/Delete operations to the [*ResourceServer*](https://octelium.com/docs/octelium/latest/reference/components.md#resource-server) and store the *Secret* in your secret store according to your specific requirements.

> **Note:**
>
> Octelium provides a commercial, scalable *Secret* encryption-at-rest management that integrates with AWS KMS, Google Cloud KMS, Azure Key Vault, HashiCorp Vault, and other secret managers and vaults on-demand. You can see the list of our offerings [here](https://octelium.com/enterprise).

## API Reference

[Secret JSON Schema (Octelium core/v1, latest documentation)](https://octelium.com/schemas/octelium/latest/core.v1.Secret.schema.json)