Secret Manager is a central, managed place to keep the sensitive values your applications need at run time.

What is a secret?

A secret is any piece of information that would cause harm if it fell into the wrong hands and that your software needs in order to work. Database passwords, API keys for payment or messaging providers, signing keys, access tokens, private certificates and encryption passphrases are all secrets. They are different from ordinary settings, such as a page title or a timeout, which can be public without harm.

The problem of scattered secrets

Without a proper place to keep them, secrets end up in the worst locations. Developers paste them into source code, where they are copied to every laptop and every backup. Teams put them in configuration files that are committed to version control. They place them in plain environment settings that appear in logs and error pages. They share them in chat messages and documents. Once a secret has spread this widely, nobody can say who has it, and changing it becomes a frightening project.

What the service does

Secret Manager is a fully managed service that stores secrets as text or binary data, encrypts them, and releases them only to identities that you authorize. Every secret has versions, so you can change a value without losing history. Every access can be recorded in audit logs. Applications fetch secrets when they need them, rather than carrying them around. It becomes the single source of truth for sensitive values in your Google Cloud environment.

Twelve words you will meet in every Secret Manager conversation.

Keep this list close. Each word returns with examples later, and the key idea to hold on to is this: the secret is the container, and the versions hold the values.

The simplest security improvement most teams can make is to take secrets out of their code.

Source code is shared widely. It is copied to developer machines, stored in repositories, built into images, backed up and sometimes published by accident. A secret placed in code inherits all of this exposure, and it stays in the history of version control even after the line is deleted. Attackers know this and scan public and leaked repositories constantly for keys and passwords.

flowchart LR
subgraph BAD["Without Secret Manager"]
C1["Code"] --- S1["Password inside"]
F1["Config file"] --- S2["Key inside"]
I1["Image"] --- S3["Token inside"]
end
subgraph GOOD["With Secret Manager"]
APP["Application"] -->|"Asks with its identity"| SM["Secret Manager"]
SM -->|"Releases the value if allowed"| APP
end
        

How the pieces are organized inside your project.

Inside a Google Cloud project you create secrets. Each secret has a name that is unique in the project, and settings such as labels and replication. Under each secret sit versions, numbered one, two, three and so on, each holding a payload. Applications almost always work with versions, not with the secret container. Access to a secret and to its versions is controlled with identity and access management.

flowchart TD
P["Google Cloud Project"] --> S1["Secret: database-password"]
P --> S2["Secret: payment-api-key"]
S1 --> V1["Version 1: disabled"]
S1 --> V2["Version 2: enabled"]
S1 --> V3["Version 3: enabled, latest"]
S2 --> V4["Version 1: enabled, latest"]
        

Immutable versions

A version can never be edited. To change a secret, you add a new version. This is a valuable safety feature. You always know exactly which value was in use at any time, you can roll back to a previous version, and a mistaken update never destroys the old value.

Regional and global thinking

Secret names are resources of the whole project, while the secret data is stored in regions that you choose, or that Google chooses for you. Newer regional secrets are created and accessed through regional endpoints, so that both the data and the requests stay in a chosen location. This matters for data residency rules and for latency.

A version moves through a small number of states, and each state has a meaning.

flowchart LR
A["Add version: Enabled"] --> B["Disable"]
B --> A
B --> C["Destroy requested"]
C -->|"Delay configured"| D["Scheduled for destruction"]
D -->|"Admin restores"| B
D -->|"Delay ends"| E["Destroyed"]
C -->|"No delay"| E
        

Disable first, destroy later

The safest way to retire a value is a staged one. First add the new version and move applications to it. Then disable the old version and watch for errors. If nothing breaks after an agreed period, destroy it. Because destroying is permanent by default, many teams turn on delayed destruction, which gives a recovery window in case a version turns out to be needed after all.

Follow a secret from the moment you save it to the moment an application reads it.

sequenceDiagram
participant A as Administrator
participant SM as Secret Manager
participant K as Encryption Layer
participant App as Application
participant IAM as IAM
A->>SM: Create secret and add version
SM->>K: Encrypt payload
K-->>SM: Encrypted data stored
App->>SM: Access version using service account
SM->>IAM: Is this identity allowed?
IAM-->>SM: Yes
SM->>K: Decrypt payload
SM-->>App: Return payload over encrypted connection
SM->>SM: Write audit log entry
        

Decide exactly who can read, who can add values and who can manage.

Secret Manager uses Google Cloud identity and access management. Roles can be granted at the project level, which covers all secrets, or on a single secret, which is far safer. The most important idea is the separation between managing a secret and reading its value. A person who administers secrets does not automatically need to see their contents, and an application that reads a value does not need to change it.

Where your secret data is physically stored, and how it survives failures.

A secret that is stored in only one place is lost if that place fails, and an application that cannot read its database password cannot start. Replication stores copies in multiple locations so that secrets are durable and available. You choose a replication policy when you create a secret.

flowchart TD
SEC["Secret: payment-api-key"] --> POL{"Replication policy"}
POL -->|"Automatic"| AUTO["Google chooses locations"]
POL -->|"User-managed"| UM["You choose regions"]
UM --> R1["Region A copy"]
UM --> R2["Region B copy"]
        

Secret data is always encrypted, and you can decide who holds the key.

By default, Secret Manager encrypts secret data at rest with keys managed by Google, and data in transit travels over encrypted connections. Some organizations must control the encryption key themselves, for example to satisfy a regulator or to be able to cut off access instantly. For these cases Secret Manager supports customer-managed encryption keys, using Cloud KMS. You create a key, grant the service permission to use it, and attach it to the secret. If the key is disabled or destroyed, the secret data becomes unreadable.

A secret that never changes is a secret that is waiting to be stolen.

Rotation means replacing a secret with a fresh value regularly, so that a leaked or forgotten old value stops being useful. Rotation limits the damage window: if an attacker steals a password that expires in thirty days, their access ends. Many security standards require rotation for sensitive credentials.

What Secret Manager does, and what you do

Secret Manager can send a notification when a rotation is due. You attach a rotation schedule to the secret, with a period and the time of the next rotation, and configure Pub/Sub topics. At the scheduled time Secret Manager publishes a rotation message. It does not change the password in the target system itself. That part is yours: a small function or service listens for the message, creates a new credential in the database or provider, and adds it as a new version of the secret.

flowchart LR
SCH["Rotation schedule on the secret"] --> PS["Pub/Sub notification"]
PS --> FN["Rotation function or service"]
FN --> TGT["Create new credential in target system"]
FN --> NV["Add new secret version"]
NV --> APP["Applications read latest"]
FN --> OLD["Disable old version later"]
        

Choosing which version an application reads is a design decision with real consequences.

When an application reads a secret, it names a version. There are three styles. It can ask for a specific number, such as version four, which never changes and is fully predictable. It can ask for latest, which always follows the newest enabled version. Or it can ask for an alias, such as stable, which you move between versions yourself. Each style has a place.

How applications actually receive their secrets on different platforms.

Environment variable or mounted file?

Both work, but they behave differently. Environment variables are simple and widely supported, but they are fixed when the instance starts, and they can show up in diagnostic output if handled carelessly. Mounted files can be refreshed, are less likely to leak in logs and are a good choice for certificates and larger values. For secrets that rotate while the application runs, a mounted file or an on-demand fetch is usually better.

flowchart TD
RUN["Cloud Run service with service account"] --> SM["Secret Manager"]
SM -->|"Value as environment variable at start"| ENV["Application process"]
SM -->|"Value as mounted file"| FILE["Application reads file when needed"]
        

The best secret is the one that does not exist.

Before storing a secret, ask whether it is needed at all. Many secrets exist only because older systems used long-lived keys. Google Cloud offers ways to avoid them. Services running on Google Cloud can use attached service accounts, which obtain short-lived credentials automatically, so no key file is ever created. Workloads outside Google Cloud can use workload identity federation to exchange their own identity for temporary Google credentials. Databases can often use identity based login instead of passwords.

Knowing who touched a secret is as important as protecting it.

Secret Manager works with Cloud Audit Logs. Administrative actions, such as creating a secret, changing its permissions or destroying a version, are recorded. Data access events, such as reading a secret value, can be recorded as well, but data access logging may need to be enabled and can add log volume and cost. For sensitive secrets, enabling data access logs is usually worth it, because it lets you answer who read this value and when.

Several extra layers make a good vault much harder to abuse.

Costs are small per secret, but they scale with the number of versions and the number of reads.

Secret Manager pricing has three main parts. Active secret versions are billed per version, per location, per month, while destroyed versions are free. Access operations, meaning reads of secret values, are billed per set of operations. Rotation notifications sent to Pub/Sub are billed per message. Management operations, such as creating secrets and versions, are not billed. A small free allowance exists. Exact rates and allowances change over time, so always use the official pricing page and calculator.

Where a central vault quietly prevents breaches.

These are common patterns rather than named customer stories, because specific designs change over time.

A managed vault removes a lot of risk and asks for discipline in return.

Habits that keep secrets safe, and habits that quietly undo the protection.

Patterns that work

Strong teams give each application its own service account and grant it access to only its own secrets. They separate environments into projects. They fetch secrets at run time, cache them briefly and handle fetch failures gracefully. They automate rotation, and they keep a short, tested process for emergency replacement. They enable audit logs for sensitive secrets, and they prefer identity based access to stored keys wherever possible.

A checklist to keep your secrets safe, tidy and manageable.

Mistakes beginners make most often

The first is leaving old secrets in code and repository history. The second is granting broad project-level access. The third is logging secret values. The fourth is skipping rotation. The fifth is reading the secret on every request. The sixth is mixing environments in one project. The seventh is destroying a version without first disabling it, and finding out the hard way that something still used it.

Google Cloud has several services that touch on keys and sensitive data, and each has its own job.

flowchart TD
Q1{"Is the value sensitive and small?"} -->|No| CFG["Use configuration or file storage"]
Q1 -->|Yes| Q2{"Can the workload use identity instead of a stored value?"}
Q2 -->|Yes| ID["Use service account or federation"]
Q2 -->|No| Q3{"Must you perform encryption or signing without seeing the key?"}
Q3 -->|Yes| KMS["Cloud KMS"]
Q3 -->|No| SM["Secret Manager"]
        

KMS and Secret Manager together

The two services work well together. Secret Manager can use a key from Cloud KMS to encrypt secret data. An application might use KMS to encrypt a large piece of data, and store the small data key in Secret Manager. Each does what it does best.

It is Google Cloud’s managed service for storing, controlling access to, auditing and rotating sensitive values such as passwords, API keys and certificates.

A secret is the named container with its settings. A version holds one actual value. Versions are immutable, so changing a secret means adding a new version.

It runs with a service account that has the accessor role on that specific secret, and it requests the value at run time, either through a client library or through a platform feature that exposes the secret as an environment variable or a mounted file.

It can send a rotation notification on a schedule, but it does not change the credential in the target system for you. You provide the automation that creates the new credential and adds a new version.

It is a floating label that always points to the newest enabled version. You can also pin a specific number, or use a custom alias that you control.

By default, destruction is immediate and permanent. If delayed destruction is configured, the version is disabled and recoverable until the delay ends, and an administrator can restore it.

In the locations set by the replication policy. Automatic replication lets Google choose, user-managed replication lets you choose regions, and regional secrets keep data and requests in one chosen region.

Environment variables are simple but fixed at start and easier to leak through diagnostics. Mounted files can be refreshed and suit certificates and values that rotate. Choose according to your rotation needs.

Mainly by active secret versions per location and by access operations, with a small free allowance and free management operations. Rotation notifications are charged per message. Check the official pricing page for current rates.

No. Secret Manager stores values your application needs to read. Cloud KMS manages encryption keys and performs cryptographic operations without exposing the key. They can be used together.

It is meant for small sensitive values, and each version has a size limit, so check the current limit. Keep large files in storage services with encryption, and store only the key or password for them in Secret Manager.

Create the replacement credential in the target system, add it as a new secret version, move applications to it, disable and then destroy the old version, and review audit logs to understand the exposure.

Secret Manager is Google Cloud’s managed vault for sensitive application values. Secrets hold immutable versions, access is controlled by IAM at the level of single secrets, data is encrypted and replicated to chosen locations, and activity can be audited. Applications read secrets at run time through their own identities, rotation is triggered by notifications and completed by your automation, and old versions are disabled before being destroyed. The best results come from removing secrets where identity can replace them, granting narrow access, rotating regularly, logging carefully and rehearsing how to respond when something leaks.