feat (Nerdgraph): Created tutorial for Secrets Management Service #19020
Conversation
cbehera-newrelic
commented
Oct 21, 2024
cbehera-newrelic
commented
- Created Nerdgraph tutorial for secrets management service
- NR-326436
cbehera-newrelic
added
content
|
Hi @cbehera-newrelic 👋 Thanks for your pull request! Your PR is in a queue, and a writer will take a look soon. We generally publish small edits within one business day, and larger edits within three days. We will automatically generate a preview of your request, and will comment with a link when the preview is ready (usually 10 to 20 minutes). |
✅ Deploy Preview for docs-website-netlify ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
|
| @@ -0,0 +1,255 @@ | |||
| --- | |||
| title: "NerdGraph tutorial: Secret Management Service" | |||
There was a problem hiding this comment.
Global comment: Check out capitalization standard for Secret Management Service. I vaguely remember we use sentence case for feature names too. So, only Secret should be initial caps. Please double-check.
There was a problem hiding this comment.
- Pridhvi had spoken about a fifth mutation that we could use to restore the specific version of a deleted/purged secret. Is that out of scope now?
- Pridhbi had mentioned three NR solutions/capabilities for which this preview is supported: Incident management, Workflows, and I-Can't-Remember-Anymore. We need to have a small section/callout in each of those docs mentioning the secret mgmt srvc and link to this GraphQL API doc from there and also cross-link to each of those solution docs from this new topic.
There was a problem hiding this comment.
As discussed with Pridhvi, we don't limit our support for the mentioned capabilities so there is no need for a callout.
There was a problem hiding this comment.
Global comment: Check out capitalization standard for Secret Management Service. I vaguely remember we use sentence case for feature names too. So, only Secret should be initial caps. Please double-check.
Thanks for pointing this out.
| 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. | ||
|
|
||
| Note that there's no data boundary for storing secrets; all secrets reside in US in a global DB enclave. |
There was a problem hiding this comment.
I think it should be in the US.
Double-check.
Semicolons make sentences unnecessarily complex. Let's split the note into two sentences.
And should we use the callout component instead? This seems like an important note.
| * **Secure Management**: Enhanced security features to protect your secrets. | ||
| * **Scalability**: Designed to handle the growing needs of enterprises. | ||
|
|
||
| ## Requirements[#review-requirements] |
There was a problem hiding this comment.
Plz check if we name this Prerequisites instead.
There was a problem hiding this comment.
Since all Nerdgraph tutorials have "requirements" sections, just to maintain consistency, I am not making any change to it.
|
|
||
| ## Requirements[#review-requirements] | ||
|
|
||
| * You need a [New Relic account](https://newrelic.com/signup), and with that account, you can access your API user key that you need to include with queries and mutations. |
There was a problem hiding this comment.
Is mutation a widely used term in technology? Is this commonly understood? Do we have anything in our standards related to its usage? Have we used this in our NerdGraph docs before?
If not, let's use a more user-friendly term such as data manipulation or CRUD operations, for example.
There was a problem hiding this comment.
graphQl mutations are industry standard and we have explained it this in our documentation and used it.
|
|
||
| ## Mutation operations | ||
|
|
||
| To enable users to interact with the Secrets Management Service, following are the exposed four NerdGraph mutations: |
There was a problem hiding this comment.
In our docs, we directly talk to our users. Let's avoid referring to them in the third person.
How about this:
Manage your secrets with these Secrete management service operations:
|
|
||
| The `secretsManagementCreateSecret` mutation allows you to add new secrets to the Secrets Management Service. | ||
|
|
||
| #### Input Parameters |
There was a problem hiding this comment.
Can we manipulate the layout to show the sample query next to the input params and the response next to the output params?
If no, can we show the sample immediately after the param? Alternatively, we could use tabs to structure them.
There was a problem hiding this comment.
Parameters should be lowercased
There was a problem hiding this comment.
Yes, this is a good suggestion. Updated accordingly
|
|
||
| #### Input Parameters | ||
|
|
||
| * `accountId` (String, required): The account ID associated with the secret. |
There was a problem hiding this comment.
Can we change the order of the attributes to match the order in which they appear in the req/res?
Do we have any pointers from the style guide?
There was a problem hiding this comment.
Also, I feel attributes are better presented in tables with the following columns:
Attribute name | Data type | Required/Optional | Description
This is for larger consideration. If that's not how we have historically documented this, please ignore for now. But let's discuss its merits/demerits.
|
|
||
| * `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. |
There was a problem hiding this comment.
How will a user get the GUID and the account ID? Is this info covered or obvious?
| value: "1234567890" | ||
| alias: "" | ||
| entityGuid: "" | ||
| namespace: "" |
There was a problem hiding this comment.
Isn't namespace a required attribute? We should include meaningful samples in our docs. If we don't have one, let's get it from the PM/Eng.
Ideally, we should provide working samples, which users can copy and execute.
| * `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. |
There was a problem hiding this comment.
didn't see tags in the sample response.
There was a problem hiding this comment.
The tag field is populated only if added during the request. Since this isn't a mandatary field, I didn't add it.
| ``` | ||
|
|
||
|
|
||
| ### Purge secrets[#purge-secrets] |
There was a problem hiding this comment.
Something's off about its formatting. Check the HTML output.
| * `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. |
There was a problem hiding this comment.
I think we need to add a sentence explaining what does it mean when we say a secret belongs to a namespace. Another reason why I think tables are better way to handle this content.
Namespace is an abstraction that enables devs to better organize their 'secrets', in this case. We dont need to explain what namespaces are, I agree, but we should include an example as to how this is to be used, all the more so because this is a required attr.
|
|
||
| <Callout variant="tip"> | ||
| * If `purgeAll` is true, the `version` parameter is null and ignored. | ||
| * valid combination of `purgeAll` and `version` : `true` & `null`, `false` & `non-null`. |
There was a problem hiding this comment.
(A)
purgeAll: true
version: null
OR
(B)
purgeAll: true
version:
Which one do you mean? A or B?
If A, what happens in the case of B?
|
|
||
| * `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. |
There was a problem hiding this comment.
I dont see key and tags in the sample response provided. Am I looking at the right copy, coz you told me you'll update the responses and share the draft...
Again, let's use 'meaningful' samples in our docs.
| ``` | ||
|
|
||
|
|
||
| ### Retrive a secret[#retrieve-secret] |
|
|
||
| * `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. |
There was a problem hiding this comment.
Make active voice - The key of the secret that you want to retrieve.
| * `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. |
|
|
||
| ### Update a secret[#update-secret] | ||
|
|
||
| The `secretsManagementUpdateSecret` mutation allows you to update the value of existing secrets. |
There was a problem hiding this comment.
Check what guidance we have in our style guide for allows vs. enables.
Preferably we should use enables or lets you. Allows indicates permission. I am not sure we mean that. I have seen this word used a few times in the topic. Based on what you find out, please change across instances.
|
|
||
| * `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. |
src/content/docs/apis/nerdgraph/examples/nerdgraph-api-secret-management-service.mdx
Show resolved
Hide resolved
| <CollapserGroup> | ||
| <Collapser | ||
| id="create-secret" | ||
| title="store a secret"> |
| </td> | ||
| <td> | ||
|
|
||
| * `type`: Based on your permission and need, select `Account` or `Organization`. |
There was a problem hiding this comment.
| * `type`: Based on your permission and need, select `Account` or `Organization`. | |
| * `type`: Based on your permissions and requirements, select `Account` or `Organization`. |
| Use the `secretsManagementUpdateSecret` mutation to update the value of existing secrets. | ||
|
|
||
| <Callout variant="tip"> | ||
| Each update operation creates a new version of the secret. The highest version is always the latest version of the secret. |
There was a problem hiding this comment.
Link to how to access an older version
| title="Delete a secret"> | ||
|
|
||
|
|
||
| Use the `secretsManagementDeleteSecret` mutation to delete all versions of a secret permanently or temporarily. Your assigned permissions determine the availability of these options. For more details, refer to the [Access control](#security-and-access-control) section. If you delete a secret temporarily, you can recover it using the `secretsManagementRecoverSecret` mutation. |
There was a problem hiding this comment.
Link to recover secrets?
src/content/docs/apis/nerdgraph/examples/nerdgraph-api-secret-management-service.mdx
Show resolved
Hide resolved
|
Hi @vpayyapilly . This PR is ready for your revisit. |
|
|
||
| * **Standard User**: Users can create, update, retrieve, and temporarily delete secrets. | ||
|
|
||
| * **All Product Admin**: Users have full access to the <dnt>secrets management</dnt> service. They can create, update, retrieve, temporarily or permanently delete, and fetch list of secrets. |
There was a problem hiding this comment.
Capitalisation for secrets management service is not uniform. Fix.
