Get Started With Vault Service | Predix Platform

Vault Service Setup

Task Roadmap


#	Task	Information
1	Deploy your application to Cloud Foundry.	For an example of deploying a Predix Hello World Web application to cloud foundry, see t_Deploying_an_App_to_Cloud_Foundry.html#task_xwn_lvb_vx.
2	Create an instance of the Vault service.	For more information, see vault-service-get-started.html#task_9b940213-7d86-4ae5-9bdb-44399675a930.
3	Bind your application to the service instance.	To establish communication between your application and the platform service, you must bind the application to the service. See vault-service-get-started.html#task_0c97a8d8-4ca5-42c4-8a93-10e3657b283a.
4	(optionally) Create a service key for your instance.	This is an alternative procedure to retrieve Vault credentials if you do not bind an application to your Vault service instance. See vault-service-get-started.html#task_3bbe9bb0-ff26-409e-99ee-b362f139e3ca.
5	Start using the Vault service.	See Using Vault Service.

Creating a Vault Service Instance

You can create an instance of Vault Service to securely store and manage access to tokens, passwords, API keys and other credentials.

Procedure

Sign into your Predix account at https://www.predix.io.
Navigate to Catalog > Services tab, and click the Credential Store tile.
Click Subscribe on the required plan.
On the New Service Instance page, enter:

Field Description
Org Select your org.
Space Select the space for your application.
Service instance name Specify a unique name for your instance.
Service plan Select a plan.
Click Create Service.

Field	Description
Org	Select your org.
Space	Select the space for your application.
Service instance name	Specify a unique name for your instance.
Service plan	Select a plan.

Results

The service instance is created and displayed in your console.

What To Do Next

You can retrieve the Vault Credentials from the VCAP_SERVICES environment variable after binding it to an application. Alternatively, you can retrieve the Vault Credentials by creating a service key.

Using Command Line to Create a Vault Instance

Procedure

Use the Cloud Foundry CLI to log into Cloud Foundry.
```
cf login -a <API_Endpoint>
```
Vault service is available for the users of Predix US-East domain and US-West domain. The value of <API_Endpoint> is https://api.system.asv-pr.ice.predix.io or https://api.system.aws-usw02-pr.ice.predix.io.
List the services in the Cloud Foundry marketplace.
```
cf marketplace
```
The Vault service, predix-vault, is listed as an available service.
Create a Vault service instance.
```
cf create-service predix-vault <plan> <my_vault_instance>
```
where:
- <plan> is the plan associated with a service.
- <my_vault_instance> is the service instance you are creating.
The message on the screen indicates that the instance is created.

What To Do Next

You can retrieve the Vault Credentials from the VCAP_SERVICES environment variable after binding it to an application. Alternatively, you can retrieve the Vault Credentials by creating a service key.

Binding an Application to the Vault Service Instance

You must bind your application to your Vault instance to provision its connection details in the VCAP_SERVICES environment variable. Vault service creates a token when you bind your application to the Vault service instance.

About This Task

Cloud Foundry runtime uses VCAP_SERVICES environment variable to communicate with a deployed application about its environment. When you bind your application to the Vault service instance, by default a token is created with time to live (TTL) value of 32 days. You can use custom parameters to specify a different TTL for the token and to create a read-only token.

Procedure

Use the Cloud Foundry CLI to log into Cloud Foundry.
```
cf login -a <API_Endpoint>
```
Vault service is available for the users of Predix US-East domain and US-West domain. The value of <API_Endpoint> is https://api.system.asv-pr.ice.predix.io or https://api.system.aws-usw02-pr.ice.predix.io.
List the services in your Cloud Foundry space.
```
cf services
```
Your Vault service instance, vault_instance_name, is listed as an available service.

Bind your application to the Vault instance.

cf bind-service <your_app_name> <vault_instance_name>

The <vault_instance_name> instance is bound to your application, and the following message is returned:

Binding service <vault_instance_name> to app <your_app_name> in org predix-platform / space predix as [email protected]...
OK
TIP: Use 'cf restage' to ensure your env variable changes take effect

(Optionally) You can specify custom parameters for the following:
- To specify the duration of the token for your Vault service instance.
  - For a token with unlimited duration, use the following command:
```
cf bind-service <your_app_name> <vault_instance_name> -c '{"token_type" : "perpetual"}'
```
  - For token with specific TTL value, use the following command:
```
cf bind-service <your_app_name> <vault_instance_name> -c '{"token_type" : "periodic", "token_ttl" : "<duration>"}'
```
- To add a read-only policy to the token. When you add a read-only policy, a user can read the token details but cannot create, update or delete the token. Use the following command:
```
cf bind-service <your_app_name> <vault_instance_name> -c '{" token_read_only: true "}'
```
Use the following command to verify the binding and view the environment variables:
```
cf env <your_app_name>
```

Create a Service Key for Vault Service

You can optionally retrieve Vault credentials without binding an application to a Vault instance by creating a service key.

Procedure

Use the Cloud Foundry CLI to log into Cloud Foundry.
```
cf login -a <API_Endpoint>
```
Vault service is available for the users of Predix US-East domain and US-West domain. The value of <API_Endpoint> is https://api.system.asv-pr.ice.predix.io or https://api.system.aws-usw02-pr.ice.predix.io.
List the services in your Cloud Foundry space.
```
cf services
```
Your Vault service instance <vault_instance_name> is listed as an available service.

Use the following command to create the service key.

cf create-service-key <vault_instance_name> <service-key-name>

(Optionally) You can specify custom parameters for the following:

To specify the duration of the token for your Vault service instance.

For a token with unlimited duration, use the following command:

cf create-service-key <vault_instance_name> <service-key-name> -c '{"token_type" : "perpetual"}'

For token with specific TTL value, use the following command:

cf create-service-key <vault_instance_name> <service-key-name> -c '{"token_type" : "periodic", "token_ttl" : "<duration>"}'

To add a read-only policy to the token. When you add a read-only policy, a user can read the token details but cannot create, update or delete the token. Use the following command:
```
cf create-service-key <vault_instance_name> <service-key-name> -c '{" token_read_only: true "}'
```

Retrieve the credential by reading the service key.
```
cf service-key <vault_instance_name> <service-key-name>
```
This command retrieves the following information:
- vault_accessor
  Alias of the token for Vault service instance.
- vault_token
  Token for accessing the Vault service instance. You use this token to log in to Vault dashboard.
- vault_url
  URL of the Vault service instance. You use this URL to log in to the Vault dashboard. The URL value includes the root path (as a set of GUIDs) to your Vault instance.