provision.md

copyright	years 2020, 2026
lastupdated	2026-10-30
keywords	provsion Secrets Manager, create Secrets Manager instance, dedicated instance, trial plan
subcollection	secrets-manager

{:codeblock: .codeblock} {:screen: .screen} {:download: .download} {:external: target="_blank" .external} {:faq: data-hd-content-type='faq'} {:gif: data-image-type='gif'} {:important: .important} {:note: .note} {:pre: .pre} {:tip: .tip} {:preview: .preview} {:deprecated: .deprecated} {:beta: .beta} {:term: .term} {:shortdesc: .shortdesc} {:script: data-hd-video='script'} {:support: data-reuse='support'} {:table: .aria-labeledby="caption"} {:troubleshoot: data-hd-content-type='troubleshoot'} {:help: data-hd-content-type='help'} {:tsCauses: .tsCauses} {:tsResolve: .tsResolve} {:tsSymptoms: .tsSymptoms} {:video: .video} {:step: data-tutorial-type='step'} {:tutorial: data-hd-content-type='tutorial'} {:api: .ph data-hd-interface='api'} {:cli: .ph data-hd-interface='cli'} {:ui: .ph data-hd-interface='ui'} {:terraform: .ph data-hd-interface="terraform"} {:curl: .ph data-hd-programlang='curl'} {:java: .ph data-hd-programlang='java'} {:ruby: .ph data-hd-programlang='ruby'} {:c#: .ph data-hd-programlang='c#'} {:objectc: .ph data-hd-programlang='Objective C'} {:python: .ph data-hd-programlang='python'} {:javascript: .ph data-hd-programlang='javascript'} {:php: .ph data-hd-programlang='PHP'} {:swift: .ph data-hd-programlang='swift'} {:curl: .ph data-hd-programlang='curl'} {:dotnet-standard: .ph data-hd-programlang='dotnet-standard'} {:go: .ph data-hd-programlang='go'} {:unity: .ph data-hd-programlang='unity'} {:release-note: data-hd-content-type='release-note'} {{site.data.keyword.attribute-definition-list}}

Creating a {{site.data.keyword.secrets-manager_short}} service instance

{: #create-instance}

Get started with {{site.data.keyword.secrets-manager_full}} by creating a service instance in {{site.data.keyword.cloud_notm}} console, {{site.data.keyword.cloud_notm}} CLI, or API. {: shortdesc}

Choosing a plan

{: #choosing-plan}

Before you create an instance, it's important to understand the key differences between the available plans:

Consideration	[Trial and Standard]{: tag-blue} plans	[Vault Dedicated]{: tag-green} plan
Features	IBM-managed secrets with built-in secret types and engines.	Managed HashiCorp Vault Enterprise capabilities with native Vault features.
Upgrade path	Trial can be upgraded to Standard only.	Cannot upgrade from Trial/Standard to Vault Dedicated.
Instance limits	One trial instance per account.	Multiple instances allowed.
Use case	{{site.data.keyword.cloud_notm}}-native secret management.	Enterprise Vault workloads requiring native Vault features.
{: caption="Plan comparison" caption-side="bottom"}

Key points to remember:

• Trial instances can only be upgraded to Standard plan. To use the [Vault Dedicated]{: tag-green}, you must provision a new Vault Dedicated instance.
• Only one Trial instance is allowed per account. Before creating a new Trial instance, you must delete any existing Trial instance and its reclamation.
• Features differ significantly between plans. Review the Feature overview to determine which plan best fits your needs.

Before you begin

{: #create-instance-prereqs}

Provisioning {{site.data.keyword.secrets-manager_short}} in your {{site.data.keyword.cloud_notm}} account can take 5 - 15 minutes to complete as the service creates a single tenant, dedicated instance. {: note}

Creating a {{site.data.keyword.secrets-manager_short}} instance in the UI

{: #create-instance-ui} {: ui}

To create an instance of {{site.data.keyword.secrets-manager_short}} from the {{site.data.keyword.cloud_notm}} console, complete the following steps.

1. In the console, go to the {{site.data.keyword.secrets-manager_short}} offering details page{: external}.

2. In the Create tab, select the region that represents the geographic area where you want provision your instance.

3. Review and select a pricing plan.

   You can create only one Trial instance of {{site.data.keyword.secrets-manager_short}} per account. Before you can create a new Trial instance, you must delete the existing Trial instance and its reclamation. {: note}

4. Provide a name for your instance.

5. Select a resource group.

6. Optional: Add tags to help you to organize the instance in your account.

7. Determine an option for enabling customer-managed encryption for your instance.

   You can enhance the security of your secrets at rest by integrating with a key management service. For more information about customer-managed encryption, check out Protecting your sensitive data in {{site.data.keyword.secrets-manager_short}}.

   You can also use the Key Management Services All-Inclusive module{: external} for streamlined key management. Explore Terraform IBM Modules for more.

8. Determine an option for connecting to {{site.data.keyword.secrets-manager_short}}. By default instances of Secrets Manager are created with only a private endpoint.

   Select either private-only or public-and-private. For more information about setting up your account to support the private connectivity option, see Enabling VRF and service endpoints.

9. Click Create to create an instance of {{site.data.keyword.secrets-manager_short}} in the account, region, and resource group that you selected.

   To update your service plan after you create an instance, see Updating your service plan. {: tip}

Creating a {{site.data.keyword.secrets-manager_short}} instance from the CLI

{: #create-instance-cli} {: cli}

To create an instance of {{site.data.keyword.secrets-manager_short}} by using the {{site.data.keyword.cloud_notm}} CLI, complete the following steps.

1. Log in to {{site.data.keyword.cloud_notm}} through the {{site.data.keyword.cloud_notm}} CLI{: external}.

   ibmcloud login

   {: pre}

   If the login fails, run the ibmcloud login --sso command to try again. The --sso parameter is required when you log in with a federated ID. If this option is used, go to the link listed in the CLI output to generate a one-time passcode. {: note}

2. Select the account, region, and resource group where you want to create a {{site.data.keyword.secrets-manager_short}} service instance.

   ibmcloud target -r REGION_NAME -g RESOURCE_GROUP_NAME

   {: pre}

3. Create an instance of {{site.data.keyword.secrets-manager_short}} within that account and resource group.

   ibmcloud resource service-instance-create INSTANCE_NAME secrets-manager PLAN REGION_NAME [OPTIONS]

   {: pre}

   Variable	Description
   Instance name (instance_name)	A unique alias for your service instance.
   Region (region)	The region the instance should be provisioned in. Supported regions.
   Pricing plan (plan)	The pricing plan that you want to use. Usetrial,standard or dedicated.
   Endpoints (options)	Optional. By default instances of {{site.data.keyword.secrets-manager_short}} are created with only a private endpoint (private-only). If you need to provision an instance of {{site.data.keyword.secrets-manager_short}} that uses also a public endpoint, append the --service-endpoints public-and-private option to your command.
   Encryption (options)	To provision an instance of {{site.data.keyword.secrets-manager_short}} that uses customer-managed encryption, append -p '{"kms_key": "<root_key_crn>"}'. Replace <root_key_crn> with the CRN value for the root key that you want to integrate.
   {: caption="Description of the information that is required to provision the {{site.data.keyword.secrets-manager_short}} service using CLI" caption-side="bottom"}

   You can create only one Trial instance of {{site.data.keyword.secrets-manager_short}} per account. Before you can create a new Trial instance, you must delete the existing Trial instance and its reclamation. {: note}

   To update your service plan after you create an instance, see Updating your service plan. {: tip}

For more information on the different available plans, see Feature overview.

Creating a {{site.data.keyword.secrets-manager_short}} instance from API

{: #create-instance-api} {: api}

To create an instance of {{site.data.keyword.secrets-manager_short}} from API, complete the following steps.

For additional programming languages support, see the Resource Controller API Docs. {: tip}

1. Obtain an IBM Cloud IAM access token.

2. Run a curl command to provision an instance of {{site.data.keyword.secrets-manager_short}}.

   curl -X POST https://resource-controller.cloud.ibm.com/v2/resource_instances -H "Authorization: Bearer <IAM token>" -H 'Content-Type: application/json' -d '{
      "name": "<instance_name>",
      "target": "<region>",
      "resource_group": "<resource_group_id>",
      "resource_plan_id": "<plan>",
      "parameters": {"service-endpoints": "public-and-private","kms_key": "<root_key_crn>"}
   }'

   {: pre}

   Variable	Description
   Instance name (name)	A unique alias for your service instance.
   Target (region)	The region the instance should be provisioned in. Supported regions.
   Pricing plan (plan)	The pricing plan that you want to use, provided as a plan ID. Use 869c191a-3c2a-4faf-98be-18d48f95ba1f for trial, 7713c3a8-3be8-4a9a-81bb-ee822fcaac3d for standard or dedicated.
   Endpoints	By default instances of {{site.data.keyword.secrets-manager_short}} are created with only a private endpoint. If you need to provision an instance of {{site.data.keyword.secrets-manager_short}} that uses also a public endpoint, add "service-endpoints":"public-and-private" to parameters.
   Encryption	To provision an instance of {{site.data.keyword.secrets-manager_short}} that uses customer-managed encryption, keep the kms_key parameter, and replace <root_key_crn> with the CRN value for the root key that you want to integrate.
   {: caption="Description of the information that is required to provision the {{site.data.keyword.secrets-manager_short}} service using API" caption-side="bottom"}

   You can create only one Trial instance of {{site.data.keyword.secrets-manager_short}} per account. Before you can create a new Trial instance, you must delete the existing Trial instance and its reclamation. {: note}

   To update your service plan after you create an instance, see Updating your service plan. {: tip}

For more information on the different available plans, see Feature overview.

Creating a {{site.data.keyword.secrets-manager_short}} instance using Terraform

{: #create-instance-terraform} {: terraform}

To create an instance of {{site.data.keyword.secrets-manager_short}} using Terraform, include the following parameters in your ibm_resource_instance resource for {{site.data.keyword.secrets-manager_short}}.

• service: secrets-manager
• plan: either Standard, Trial or dedicated. Learn more about the service plans
• service_endpoints: Either private or public-and-private. If not included, default is private Include the following inside parameters for further customization.
• kms_key: Root key CRN from Key Protect. If not included, default is root key that is managed by {{site.data.keyword.secrets-manager_short}}

An example resource would look like the following.

resource "ibm_resource_instance" "sm_instance" {
  name              = "demo-sm-instance"
  service           = "secrets-manager"
  plan              = "standard"
  location          = "us-south"
  service_endpoints = "public-and-private"
}

{: codeblock}

You can also use the {{site.data.keyword.secrets-manager_full}}{: external} to provision and configure {{site.data.keyword.secrets-manager_short}} instances as code. For more information about Terraform IBM Modules, see About Terraform IBM Modules. {: tip}

For more information on the different available plans, see Feature overview.

Upgrading a {{site.data.keyword.secrets-manager_short}} instance to the Standard plan

{: #upgrade-instance-standard}

When your Trial instance expires, you lose access to your secrets, and integrations. To preserve your data, and prevent any disruptions in your workflow, you must upgrade to the Standard plan before your Trial plan expires. Follow the steps to update your pricing plan. You can use the UI, API, and CLI to complete this process.

Trial plan instances can only be upgraded to the Standard plan. To use the Vault Dedicated plan, you must provision a new Vault Dedicated instance separately. {: note}