Skip to content

Commit

Permalink
feat: Initial commit for tag
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexronquillo
alexronquillo committed Apr 28, 2021
1 parent f2090e7 commit 0f9ac7c
Showing 1 changed file with 252 additions and 8 deletions.
260 changes: 252 additions & 8 deletions src/markdown-pages/build-apps/serve-publish-subscribe/tag.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,271 @@
---
path: '/build-apps/publish-deploy/tag'
duration: '30 min'
title: 'Tag your Nerdpack's release version'
title: "Tag your Nerdpack's release version"
template: 'GuideTemplate'
description: 'Learn to tag your Nerdpack's release version'
description: "Learn to tag your Nerdpack's release version"
tileShorthand:
title: 'Tag your Nerdpack's release version'
description: 'Tag your Nerdpack's release version'
title: "Tag your Nerdpack's release version"
description: "Tag your Nerdpack's release version"
tags:
- nerdpack
- tag
---

## Deploy your app
<Intro>

Deploying is applying a Nerdpack version to a specific channel (for example, BETA, or STABLE). A channel can only have one Nerdpack version deployed to it at one time. If a channel has an existing Nerdpack associated with it, deploying a new Nerdpack version to that channel will undeploy the previous one. Channels are meant to be an easier way to control application version access than having to be concerned with specific version numbers.
Tag your Nerdpack versions to track and subscribe to them. Untag versions to prevent subscriptions or hide apps and visualizations from the catalog.

</Intro>

## Check your permissions

To tag a Nerdpack version, you need:

- Access to the account that published it
- The [necessary permissions for managing Nerdpacks](/build-apps/permission-manage-apps)

## Publish your Nerdpack

You need to [publish](/build-apps/publish-deploy/publish) Nerdpacks that you create before you can tag them.

## Tag a version

After you've published a Nerdpack version to the New Relic One catalog, you can tag it with the `nr1` CLI.

<Steps>

<Step>

To deploy an application, run `nr1 nerdpack:deploy`.
In the root folder of your Nerdpack, run `nr1 nerdpack:tag`:

```sh
nr1 nerdpack:tag --tag=DEV
[output] {success}✔{normal} Tagged {purple}ab123c45-678d-9012-efg3-45hi6jkl7890{normal} version {green}1.0.0{normal} as {green}DEV{normal}.
```

Here, you tagged version `1.0.0` as `DEV`.

Now, you, and other users on your account, can use this tag:

- You see the tag as an option to subscribe to when you add the app or visualization to your account
- If you subscribe to the `DEV` tag and it gets updated later—say, `DEV` is applied to version `1.0.1`—you automatically get upgraded to the new version without having to subscribe again.

<Callout variant="important">

One of the features of tagging release versions is that users who are subscribed to a tag automatically get updates when that tag is used for another version. This means that if a user is testing one version, say `1.0.0`, and you apply that same tag to another version, say `1.0.1`, that user will see version `1.0.1` in their account, and they can no longer access the app or visualization they were testing before. Often times, this is the expected behavior, but make sure you consider this side effect when you use tags.

</Callout>

</Step>

</Steps>
<Step>

View your Nerdpack's registry information:

```sh
nr1 nerdpack:info
[output] Id: {purple}ab123c45-678d-9012-efg3-45hi6jkl7890
[output] Region: {muted}us
[output] Account ID: 1234567
[output] Local version: 1.0.0
[output] Subscription Model: OWNER_AND_ALLOWED
[output] Version Count: 1
[output]
[output] Version Date Tags
[output] ------- ----------- ----
[output] 1.0.0 {muted}5 hours ago{green} DEV
```

This output confirms your `DEV` tag on version `1.0.0`.

</Step>

</Steps>

## Untag a version

As you build more versions of your Nerdpack, you may update your tags to newer versions. However, you can also remove a tag from your Nerdpack with `nr1`.

<Steps>

<Step>

From your Nerdpack's root directory, view your registry information:

```sh
nr1 nerdpack:info
[output] Id: {purple}ab123c45-678d-9012-efg3-45hi6jkl7890
[output] Region: {muted}us
[output] Account ID: 1234567
[output] Local version: 1.0.0
[output] Subscription Model: OWNER_AND_ALLOWED
[output] Version Count: 1
[output]
[output] Version Date Tags
[output] ------- ----------------- ----
[output] 2.0.0 {muted}a few seconds ago{green} DEV
[output] 1.0.1 {muted}8 minutes ago{green} BETA, STABLE
[output] 1.0.0 {muted}6 hours ago
```

Here, you see that version `1.0.0` has no tags, version `1.0.1` has two tags, `BETA` and `STABLE`, and version `2.0.0` has one tag, `DEV`.

</Step>

<Step>

Remove the `BETA` tag from your Nerdpack versions:

```sh
nr1 nerdpack:untag --tag=BETA
[output] {success}✔{normal} Removed nerdpack {purple}ab123c45-678d-9012-efg3-45hi6jkl7890{normal} tag {green}BETA{normal}.
```

</Step>

<Step>

Verify that the tag was removed from your Nerdpack:

```sh
nr1 nerdpack:info
[output] Id: {purple}ab123c45-678d-9012-efg3-45hi6jkl7890
[output] Region: {muted}us
[output] Account ID: 1234567
[output] Local version: 1.0.0
[output] Subscription Model: OWNER_AND_ALLOWED
[output] Version Count: 1
[output]
[output] Version Date Tags
[output] ------- -------------- ----
[output] 2.0.0 {muted}5 minutes ago{green} DEV
[output] 1.0.1 {muted}13 minutes ago{green} STABLE
[output] 1.0.0 {muted}6 hours ago
```
</Step>

</Steps>

## Resolve issues with tagging a Nerdpack version

Sometimes, when you tag to a Nerdpack version, you may come across issues. Whether you can't tag your Nerdpack or you can't untag your Nerdpack, consider some common solutions for resolving these issues.

### Publish your Nerdpack

If you try to tag your Nerdpack without first publishing it, you'll get an error:

```sh
nr1 nerdpack:tag --tag=DEV
[output] {error}›{normal} Error: A downstream error occurred.
```

This error message doesn't say much, but you can use the `--verbose` option to see more information:

```sh
nr1 nerdpack:tag --tag=DEV --verbose
[output] init version: @oclif/command@1.8.0 argv: [ {green}'--tag=DEV'{normal}, {green}'--verbose'{normal}, [length]: {yellow}2{normal} ]
[output] {blue}dist/metadata.json{normal} does not exist. package.json will be used instead.
[output] Using profile {muted}account-1234567
[output] {purple}Request:{normal} POST https://api.newrelic.com/graphql
[output] {purple}Data:{green} mutation {
[output] {green}nerdpackTagVersion(
[output] {green}nerdpackId: "ab123c45-678d-9012-efg3-45hi6jkl7890",
[output] {green}versionTag: {
[output] {green}tag: "DEV",
[output] {green}version: "1.0.0"
[output] {green}}
[output] {green}) {
[output] {green}nerdpackId
[output] {green}tags
[output] {green}version
[output] {green}}
[output] {green}}
[output] {purple}Headers: {
[output] {green}'API-Key'{normal}: {green}'<YOU USER KEY>'{normal},
[output] {green}'Content-Type'{normal}: {green}'application/graphql'
[output] }
```
This more verbose error message shows the GraphQL that runs behind the scenes for `nr1 nerdpack:tag`. The important part of the message here is:
```sh
[output] {blue}dist/metadata.json{normal} does not exist. package.json will be used instead.
```
The _dist_ directory is created when you publish your app. So, because it hasn't been published yet, this directory doesn't exist and `nr1` falls back to _package.json_ to look for details about your Nerdpack. But, because the UUID in your _package.json_ isn't in the New Relic registry, the command failed.
So, before you tag your versions, publish them to the registry:
```sh
nr1 nerdpack:publish
nr1 nerdpack:tag --tag=DEV
```
<Callout variant="tip">
Remember that you can also tag a version at the same time you deploy it!
```sh
nr1 nerdpack:publish --tag=DEV
```
</Callout>
### Unsubscribe from the app or visualization
You can only remove tags that have no subscribers. If you try to remove a tag that users are subscribed to, you'll get an error:
```sh
nr1 nerdpack:info
[output] Id: {purple}ab123c45-678d-9012-efg3-45hi6jkl7890
[output] Region: {muted}us
[output] Account ID: 1234567
[output] Local version: 2.0.0
[output] Subscription Model: OWNER_AND_ALLOWED
[output] Version Count: 3
[output]
[output] Version Date Tags
[output] ------- ----------- ----
[output] 2.0.0 {muted}an hour ago {green}DEV
[output] 1.0.1 {muted}an hour ago
[output] 1.0.0 {muted}6 hours ago
[output]
nr1 nerdpack:untag -t DEV
[output] {error}›{normal} Error: A downstream error occurred.
```
In this case, check to see if you're subscribed to the app or visualization:
```sh
nr1 subscription:list
[output] {muted}Listing subscribed deployed nerdpacks on your account:
[output] Version UUID Name Date User
[output] ------- ------------------------------------ ----------------- ----------- ----------
[output] 2.0.0 {purple}ab123c45-678d-9012-efg3-45hi6jkl7890{normal} MyAwesomeNerdpack {muted}an hour ago 1000383529
```
This shows that you're subscribed to `MyAwesomeNerdpack`. Unsubscribe, then try to remove the `DEV` tag again:
```sh
nr1 nerdpack:unsubscribe
[output] Unsubscribed account {green}1234567{normal} from the nerdpack {purple}ab123c45-678d-9012-efg3-45hi6jkl7890{normal} on the {green}DEV{normal} channel.
[output]
nr1 nerdpack:untag --tag=DEV
[output] {success}✔{normal} Removed nerdpack {purple}ab123c45-678d-9012-efg3-45hi6jkl7890{normal} tag {green}DEV{normal}.
[output]
nr1 nerdpack:info
[output] Id: {purple}ab123c45-678d-9012-efg3-45hi6jkl7890
[output] Region: {muted}us
[output] Account ID: {green}1234567
[output] Local version: 2.0.0
[output] Subscription Model: OWNER_AND_ALLOWED
[output] Version Count: 3
[output]
[output] Version Date Tags
[output] ------- ----------- ----
[output] 2.0.0 {muted}an hour ago
[output] 1.0.1 {muted}an hour ago
[output] 1.0.0 {muted}6 hours ago
```

0 comments on commit 0f9ac7c

Please sign in to comment.