diff --git a/src/content/docs/apis/nerdgraph/examples/nerdgraph-api-secret-management-service.mdx b/src/content/docs/apis/nerdgraph/examples/nerdgraph-api-secret-management-service.mdx index 0c61b09c165..7f9d81c8229 100644 --- a/src/content/docs/apis/nerdgraph/examples/nerdgraph-api-secret-management-service.mdx +++ b/src/content/docs/apis/nerdgraph/examples/nerdgraph-api-secret-management-service.mdx @@ -1,5 +1,5 @@ --- -title: "NerdGraph tutorial: Secret Management Service" +title: "NerdGraph tutorial: Secrets management service" metaDescription: "Learn how to use the Secret Management Service to securely store and manage your secrets." freshnessValidatedDate: never --- @@ -10,18 +10,19 @@ freshnessValidatedDate: never This feature is currently provided as part of a preview program pursuant to our [pre-release policies](/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy). -The Secret Management Service is a secure and scalable way to store and manage your secrets. It provides a centralized location for storing and managing secrets, such as API keys to reduce fragmentation and complexity across different services in New Relic. -You can store any string value as a secret, and call them programatically during runtime. +The Secrets management service provides a secure way to store and retrieve secrets, such as tokens, API keys, passwords, or certificates, through a centralized location using our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/). It supports storing any string value as a secret, helping to improve your security by removing the need to hard-code secrets within New Relic platform. -Note that there's no data boundary for storing secrets; all secrets reside in US in a global DB enclave. + +* Secrets stored within this service are intended to be used within New Relic applications only. Retrieving secrets for external applications or products is not recommended. -Use the [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/) to interact with the Secret Management Service. This tutorial will guide you through the process of creating, updating, and deleting secrets using the Secret Management Service. +* For EU customers, secrets are stored in a US-based global database, which is not GDPR compliant. You must provide your consent before using the service. + -## Key features +{/* ## Key features * **Centralized Repository**: Store all your confidential keys and credentials in one secure location. * **Secure Management**: Enhanced security features to protect your secrets. -* **Scalability**: Designed to handle the growing needs of enterprises. +* **Scalability**: Designed to handle the growing needs of enterprises. */} ## Requirements[#review-requirements] @@ -29,31 +30,113 @@ Use the [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/get-starte * User type and assigned roles can affect your NerdGraph permissions. For more details, see [Factors affecting access](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/factors-affecting-access-features-data/#user-permissions). -## Mutation operations - -To enable users to interact with the Secrets Management Service, following are the exposed four NerdGraph mutations: - - -### Create a secret[#create-secret] - -The `secretsManagementCreateSecret` mutation allows you to add new secrets to the Secrets Management Service. - -#### Input Parameters - -* `accountId` (String, required): The account ID associated with the secret. -* `alias` (String, optional): An alias for the secret. -* `entityGuid` (String, optional): The entity GUID associated with the secret. -* `key` (String, required): The key for the secret. -* `namespace` (String, required): The namespace to which the secret belongs. -* `value` (SecureValue, required): The value of the secret. - -#### Response - -* `createdAt` (String): The time the secret was created. -* `updatedAt` (String): The time the secret was last updated. -* `key` (String): The key of the created secret. -* `latestVersion` (String): The version of the created secret. -* `tags` (Array): Metadata associated with the secret. +## Mutations [#nerdgraph-mutations] + +Manage your secrets with the following [NerdGraph mutations](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/#terminology): + + + +{/* ### Create a secret[#create-secret] */} + +Use `secretsManagementCreateSecret` mutation to create secrets with the following attributes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `accountId` + + String + + (Required) The account ID associated with the secret. +
+ `alias` + + String + + (Optional) An alias is a way to assign a different name to a field or value in Nerdgraph query. This can be useful for readability, avoiding naming conflicts, or when you want to query the same field multiple times with different attributes. +
+ `entityGuid` + + String + + (Optional) The entity GUID is a unique identifier assigned to each entity within the New Relic ecosystem. An entity can be any monitored object, such as an application, service, host, or container, among others. The GUID is used to uniquely identify and reference these entities across various New Relic services and APIs, including NerdGraph. +
+ `key` + + String + + (Required) The key for the secret. +
+ `meta/tags` + + Array + + (Optional) A tag is a key-value pair that you can use to add metadata to your entities (such as applications, services, hosts, etc.). Tags help you organize, filter, and manage your entities more effectively. They are particularly useful for grouping related entities +
+ `namespace` + + String + + (Optional) The namespace is a logical grouping for tags. It helps to organize and categorize tags, making it easier to manage and avoid potential conflicts, especially when dealing with a large number of tags across various entities. Namespaces can be particularly useful in environments where multiple teams or projects are using New Relic, ensuring that tags are consistently applied and understood. +
+ `value` + + String + + (Required) The value of the secret. +
#### Sample query: @@ -63,9 +146,6 @@ mutation { accountId: 12345678 key: "test_user_key" value: "1234567890" - alias: "" - entityGuid: "" - namespace: "" ) { createdAt latestVersion @@ -74,6 +154,86 @@ mutation { } ``` + + +#### Response + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `createdAt` + + String + + The time the secret was created. +
+ `key` + + String + + The key of the secret. +
+ `latestVersion` + + String + + The version of the created secret. +
+ `tags` + + Array + + Metadata associated with the secret. +
+ `updatedAt` + + String + + The time the secret was last updated. +
+ + #### Smaple response: ```json @@ -88,29 +248,254 @@ mutation { } ``` + + + + + +Use the `secretsManagementDeleteSecret` mutation for a soft delete operation. The secret is not permanently deleted from the secrets management service. You can restore the secret by creating a new version of the secret with the same key. + +#### Input attributes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `accountId` + + String + + (Required) The account ID associated with the secret. +
+ `deleteAll` + + Boolean + + (Required) If true, it deletes all versions of the secret. +
+ `key` + + String + + (Required) The key for the secret that you want to delete. +
+ `namespace` + + String + + (Optional) If provided, deletes the associated namespace. +
+ `version` + + String + + (Optional) The version of the secret that you want to delete. +
-### Purge secrets[#purge-secrets] +#### Sample query: -The `secretsManagementPurgeSecret` mutation allows you to delete secrets from the Secrets Management Service. You can delete a specific version of a secret or all versions of a secret. +```graphql -#### Input Parameters +mutation { + secretsManagementDeleteSecret( + accountId: 12345678 + key: "test_user_key" + deleteAll: true + ) { + key + latestVersion + tags + } +} -* `accountId` (String, required): The account ID associated with the secret. -* `key` (String, required): The key for the secret. -* `namespace` (String, optional): The namespace to which the secret belongs. -* `purgeAll` (Boolean, required): If true, all versions of the secret are deleted. -* `version` (String, optional): The version of the secret to delete. +``` - - * If `purgeAll` is true, the `version` parameter is null and ignored. - * valid combination of `purgeAll` and `version` : `true` & `null`, `false` & `non-null`. - #### Response -* `key` (String): The key of the created secret. -* `latestVersion` (String): The latest version available corresponding to the key. If `purgeAll` is true or no version is available after purge, latestVersion will be null. -* `tags` (Array): Metadata associated with the secret. + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `key` + + String + + The key of the created secret. +
+ `latestVersion` + + String + + The latest version available corresponding to the key. If `deleteAll` is true or no version is available after delete, `latestVersion` will be null. +
+ + +#### Sample response: + +```json +{ + "data": { + "secretsManagementDeleteSecret": { + "latestVersion": null + } + }, +} +``` + + + + + +Use the `secretsManagementPurgeSecret` mutation for a hard delete operation. The secret key is permanently deleted from the secrets management service and cannot be restored. + + +#### Input attributes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `accountId` + + String + + (Required) The account ID associated with the secret. +
+ `key` + + String + + (Required) The secret key that you permanently want to delete. +
+ `namespace` + + String + + (Optional) If provided, deletes the associated namespace permanently. +
+ `purgeAll` + + Boolean + + (Required)If true, it deletes all versions of the secret permanently. +
+ `version` + + String + + (Optional)The version of the secret to delete permanently. +
+ + + * If `purgeAll` is true, the `version` parameter is null and ignored. + #### Sample query: @@ -120,18 +505,59 @@ mutation { secretsManagementPurgeSecret( accountId: 12345678 key: "test_user_key" - namespace: "" purgeAll: true - version: "" ) { key latestVersion - tags } } ``` +#### Response + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `key` + + String + + Associated secret key. +
+ `latestVersion` + + String + + The available latest version corresponding to the key. If `purgeAll` is true or no version is available after purge, latestVersion will be null. +
+ + #### Sample response: ```json @@ -143,73 +569,392 @@ mutation { }, } ``` + + + + +Use `secretsManagementRecoverSecret` mutation to recover secrets that were previously deleted using the `secretsManagementDeleteSecret` mutation. + +#### Input attributes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `accountId` + + String + + (Required) The account ID associated with the secret. +
+ `key` + + String + + (Required) The key for the secret. +
+ `namespace` + + String + + (Optional) The namespace to which the secret belongs. +
+ `recoverAll` + + Boolean + + (Required) If true, you can recover all versions of the secrets. +
+ `version` + + String + + (Optional) The version of the secret that you want to recover. +
+#### Sample query: -### Retrive a secret[#retrieve-secret] +```graphql +mutation { + secretsManagementRecoverSecret( + accountId: 12345678 + key: "test_user_key" + recoverAll: true + ) { + key + latestVersion + + } +} +``` -The `secretsManagementRetrieveSecret` mutation allows you to access the value of stored secrets. +#### Response -#### Input Parameters -* `accountId` (String, required): The account ID associated with the secret. -* `namespace` (String, optional): The namespace to which the secret belongs. -* `key` (String, required): The key of the secret that needs to be retrieved. -* `version`(String, required): The version of the secret that needs to be retrieved. + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `key` + + String + + The recovered key. +
+ `latestVersion` + + String + + The latest version of the recovered secret. +
-#### Response +#### Sample response: -* `value` (SecureValue, required): The value of the secret. -* `tags` (Array): Metadata associated with the secret. -* `createdAt` (String): The time the secret was created. +```json +{ + "data": { + "secretsManagementRecoverSecret": { + "key": "test_user_key", + "latestVersion": "1" + } + }, +} +``` + + + + + + +Retrieve the value of a secret using the `secretsManagementRetrieveSecret` mutation. + +### Input attributes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `accountId` + + String + + (Required) The account ID associated with the secret. +
+ `key` + + String + + (Required) The key of the secret for which you want to retrive the value. +
+ `namespace` + + String + + (Optional) The namespace to which the secret belongs. +
+ `version` + + String + + (Optional) The version of the secret that you want to retrieve. +
#### Sample query: ```graphql -query { +mutation { secretsManagementRetrieveSecret( - namespace: "test" - key: "test_user_key" - version: "" - ) { + accountId: 12345678 + key: " + test_user_key" + ) { + key value - tags - createdAt } } ``` +#### Response + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `createdAt` + + String + + The time the secret was created. +
+ `tags` + + String + + The tags associated with the secret. +
+ `value` + + String + + The value of the secret. +
+ #### Sample response: ```json { "data": { - "secretsManagementRetrieveSecret": { - "value": "1234567890", - "tags": [], - "createdAt": "2021-09-29T10:00:00Z" - } + "secretsManagementRetrieveSecret + ": { + "key": "test_user_key", + "value": "1234567890" + } } } ``` + + -### Update a secret[#update-secret] -The `secretsManagementUpdateSecret` mutation allows you to update the value of existing secrets. +Use the `secretsManagementUpdateSecret` mutation to update the value of existing secrets. #### Input Parameters -* `accountId` (String, required): The account ID associated with the secret. -* `namespace` (String, optional): The namespace to which the secret belongs. -* `key` (String, required): The key of the secret that needs to be updated. -* `value` (String, required): The secret value that you want to update. - -#### Response - -* `createdAt` (String): The time the secret was created. -* `updatedAt` (String): The time the secret was last updated. -* `key` (String): The key of the created secret. -* `latestVersion` (String): The version of the created secret. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `accountId` + + String + + (Required) The account ID associated with the secret. +
+ `key` + + String + + (Required) The key of the secret for which you want to update the value. +
+ `namespace` + + String + + (Optional) The namespace to which the secret belongs. +
+ `value` + + String + + (Required) The updated value for the key. +
#### Sample query: @@ -218,7 +963,7 @@ mutation { secretsManagementUpdateSecret( namespace: "test" key: "test_user_key" - value: "1234567890" + value: "24680" ) { key latestVersion @@ -228,6 +973,70 @@ mutation { } ``` +#### Response + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **Attribute name** + + **Data type** + + **Description** +
+ `createdAt` + + String + + The time the secret was created. +
+ `key` + + String + + The key of the secret. +
+ `latestVersion` + + String + + The version of the created secret. +
+ `updatedAt` + + String + + The time the secret was last updated. +
+ #### Sample response: ```json @@ -235,12 +1044,15 @@ mutation { "data": { "secretsManagementUpdateSecret": { "createdAt": "2024-10-21T08:01:07.593140Z", + "key": "test_user_key", "latestVersion": 0, "updatedAt": "2024-10-21T08:03:26.334448074Z" } }, } ``` + + diff --git a/src/content/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph.mdx b/src/content/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph.mdx index 0f7073aff96..554c2fe4eba 100644 --- a/src/content/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph.mdx +++ b/src/content/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph.mdx @@ -299,6 +299,22 @@ Here are all our available NerdGraph docs: [View and configure workloads](/docs/apis/nerdgraph/tutorials/nerdgraph-workloads-api-tutorials) + + + + Secrets management service + + + + [Create and manage secrets](/docs/apis/nerdgraph/examples/nerdgraph-api-secrets-management-service) + + + We're still working on this feature, but we'd love for you to try it out! + + This feature is currently provided as part of a preview program pursuant to our [pre-release policies](/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy). + + +