automation-instructions

Validated on 1 Jul 2024 • Last edited on 22 Nov 2024

Automatically insert details on how to perform an action with the API and CLI.

{{< automation-instructions
    command="<doctl command>"
    path="<api endpoint>" verb="<http verb>"
>}}

This shortcode uses the DigitalOcean OpenAPI spec (stored in the /data folder) and YAML metadata of the doctl CLI reference to generate detailed instructions on performing actions via the API and CLI.

You cannot currently use this shortcode with the Spaces or Metadata APIs.

Parameters

To include doctl instructions, define the following parameters. Omit them to exclude doctl instructions.

  • command: The full doctl command that performs the action.

To include API instructions, define the following parameters. Omit them to exclude API instructions.

  • path: The API endpoint that performs the action. You can find this in the right column of the API reference docs.

    For example, the blue badge that says POST next to the Create a New Droplet API action uses the /v2/droplets endpoint.

  • verb: The HTTP verb (get, post, delete, put, or patch) that corresponds with the action.

Optionally, include the action parameter to override the default description synopsis from the API spec or CLI docs:

  • action (optional): A short, English description of the action being taken.

Examples

With API and doctl Instructions

{{< automation-instructions action="create a Droplet"
    command="doctl compute droplet create"
    path="/v2/droplets" verb="post"
>}}

Renders to:

How to Create a Droplet Using the DigitalOcean CLI

  1. Install doctl, the DigitalOcean command-line tool.

  2. Create a personal access token and save it for use with doctl.

  3. Use the token to grant doctl access to your DigitalOcean account.

              doctl auth init

  4. Finally, run doctl compute droplet create. Basic usage looks like this, but you can read the usage docs for more details:

                doctl compute droplet create <droplet-name>... [flags]

    The following example creates a Droplet named example-droplet with a two vCPUs, two GiB of RAM, and 20 GBs of disk space. The Droplet is created in the nyc1 region and is based on the ubuntu-20-04-x64 image. Additionally, the command uses the --user-data flag to run a Bash script the first time the Droplet boots up:

                  doctl compute droplet create example-droplet --size s-2vcpu-2gb --image ubuntu-20-04-x64 --region nyc1 --user-data $'#!/bin/bash\n touch /root/example.txt; sudo apt update;sudo snap install doctl'
How to Create a Droplet Using the DigitalOcean API

  1. Create a personal access token and save it for use with the API.

  2. Send a POST request to https://api.digitalocean.com/v2/droplets

    cURL

    Using cURL:

                    curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"example.com","region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-20-04-x64","ssh_keys":[289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"],"backups":true,"ipv6":true,"monitoring":true,"tags":["env:prod","web"],"user_data":"#cloud-config\nruncmd:\n  - touch /test.txt\n","vpc_uuid":"760e09ef-dc84-11e8-981e-3cfdfeaae000"}' \
  "https://api.digitalocean.com/v2/droplets"

    Go

    Using Godo, the official DigitalOcean V2 API client for Go: 

                    import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    createRequest := &godo.DropletCreateRequest{
        Name:   "example.com",
        Region: "nyc3",
        Size:   "s-1vcpu-1gb",
        Image: godo.DropletCreateImage{
            Slug: "ubuntu-20-04-x64",
        },
        SSHKeys: []godo.DropletCreateSSHKey{
            godo.DropletCreateSSHKey{ID: 289794},
            godo.DropletCreateSSHKey{Fingerprint: "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"}
        },
        Backups: true,
        IPv6: true,
        Monitoring: true,
        Tags: []string{"env:prod","web"},
        UserData: "#cloud-config\nruncmd:\n  - touch /test.txt\n",
        VPCUUID: "760e09ef-dc84-11e8-981e-3cfdfeaae000",
    }

    Ruby

    Using DropletKit, the official DigitalOcean V2 API client for Ruby: 

                    require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

droplet = DropletKit::Droplet.new(
  name: 'example.com',
  region: 'nyc3',
  size: 's-1vcpu-1gb',
  image: 'ubuntu-20-04-x64',
  ssh_keys: [289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"],
  backups: true,
  ipv6: true,
  monitoring: true,
  tags: ["env:prod","web"],
  user_data: "#cloud-config\nruncmd:\n  - touch /test.txt\n",
  vpc_uuid: "760e09ef-dc84-11e8-981e-3cfdfeaae000",
)
client.droplets.create(droplet)

    Python

                    import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "example.com",
  "region": "nyc3",
  "size": "s-1vcpu-1gb",
  "image": "ubuntu-20-04-x64",
  "ssh_keys": [
    289794,
    "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
  ],
  "backups": True,
  "ipv6": True,
  "monitoring": True,
  "tags": [
    "env:prod",
    "web"
  ],
  "user_data": "#cloud-config\nruncmd:\n  - touch /test.txt\n",
  "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
}

resp = client.droplets.create(body=req)

API Only

{{< automation-instructions action="create a Droplet" path="/v2/droplets" verb="post" >}}

Renders to:

How to Create a New Droplet Using the DigitalOcean API

  1. Create a personal access token and save it for use with the API.

  2. Send a POST request to https://api.digitalocean.com/v2/droplets

    cURL

    Using cURL:

                    curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"example.com","region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-20-04-x64","ssh_keys":[289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"],"backups":true,"ipv6":true,"monitoring":true,"tags":["env:prod","web"],"user_data":"#cloud-config\nruncmd:\n  - touch /test.txt\n","vpc_uuid":"760e09ef-dc84-11e8-981e-3cfdfeaae000"}' \
  "https://api.digitalocean.com/v2/droplets"

    Go

    Using Godo, the official DigitalOcean V2 API client for Go: 

                    import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    createRequest := &godo.DropletCreateRequest{
        Name:   "example.com",
        Region: "nyc3",
        Size:   "s-1vcpu-1gb",
        Image: godo.DropletCreateImage{
            Slug: "ubuntu-20-04-x64",
        },
        SSHKeys: []godo.DropletCreateSSHKey{
            godo.DropletCreateSSHKey{ID: 289794},
            godo.DropletCreateSSHKey{Fingerprint: "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"}
        },
        Backups: true,
        IPv6: true,
        Monitoring: true,
        Tags: []string{"env:prod","web"},
        UserData: "#cloud-config\nruncmd:\n  - touch /test.txt\n",
        VPCUUID: "760e09ef-dc84-11e8-981e-3cfdfeaae000",
    }

    Ruby

    Using DropletKit, the official DigitalOcean V2 API client for Ruby: 

                    require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

droplet = DropletKit::Droplet.new(
  name: 'example.com',
  region: 'nyc3',
  size: 's-1vcpu-1gb',
  image: 'ubuntu-20-04-x64',
  ssh_keys: [289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"],
  backups: true,
  ipv6: true,
  monitoring: true,
  tags: ["env:prod","web"],
  user_data: "#cloud-config\nruncmd:\n  - touch /test.txt\n",
  vpc_uuid: "760e09ef-dc84-11e8-981e-3cfdfeaae000",
)
client.droplets.create(droplet)

    Python

                    import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "example.com",
  "region": "nyc3",
  "size": "s-1vcpu-1gb",
  "image": "ubuntu-20-04-x64",
  "ssh_keys": [
    289794,
    "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
  ],
  "backups": True,
  "ipv6": True,
  "monitoring": True,
  "tags": [
    "env:prod",
    "web"
  ],
  "user_data": "#cloud-config\nruncmd:\n  - touch /test.txt\n",
  "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
}

resp = client.droplets.create(body=req)

doctl Only

{{< automation-instructions command="doctl compute droplet create" >}}

Renders to:

How to Create a New Droplet Using the DigitalOcean CLI

  1. Install doctl, the DigitalOcean command-line tool.

  2. Create a personal access token and save it for use with doctl.

  3. Use the token to grant doctl access to your DigitalOcean account.

              doctl auth init

  4. Finally, run doctl compute droplet create. Basic usage looks like this, but you can read the usage docs for more details:

                doctl compute droplet create <droplet-name>... [flags]

    The following example creates a Droplet named example-droplet with a two vCPUs, two GiB of RAM, and 20 GBs of disk space. The Droplet is created in the nyc1 region and is based on the ubuntu-20-04-x64 image. Additionally, the command uses the --user-data flag to run a Bash script the first time the Droplet boots up:

                  doctl compute droplet create example-droplet --size s-2vcpu-2gb --image ubuntu-20-04-x64 --region nyc1 --user-data $'#!/bin/bash\n touch /root/example.txt; sudo apt update;sudo snap install doctl'

Best Practices

  • When an API or CLI call requires the resources to be in a certain state, call it out in the adjacent text.

    For an example, see the Droplet resizing docs, which call out that the Droplet must be powered down before resizing.

  • When an API or CLI call requires a slug as an input value, call it out in the adjacent text.

    For an example, see the Droplet creation docs, which call out how to retrieve valid region, machine, and image slugs.

  • Sometimes the CLI and API approaches are very different; it’s okay to include one or the other, or to split up the instructions and provide details in the adjacent text.

    For an example, see the Droplet rebuilding docs, which call out that when using the API to rebuild a Droplet, there is no specific command, like there is for doctl, and you have to set the action type to rebuild within the general droplet-action call.

    Also see the Droplet metrics docs, for which there are only API instructions, as doctl does not currently have a way to monitor things like CPU and memory usage.

Control Panel Blog Pricing Careers Terms Privacy Status API Docs Tutorials Support