DigitalOcean offers an API as an alternative to its web-based cloud control panel. The official doctl
command-line client provides an intuitive wrapper around the API. You can manage your DigitalOcean resources using an easily scriptable program interface.
Installation
Doctl is available on Windows, macOS and Linux systems. Different installation methods are supported depending on the platform. All systems can download the latest release directly from GitHub.
Most Linux distributions include doctl
in their package repositories. It is also offered as Snap-on distributions with Snap support. Using a package manager is the preferred installation mechanism as it notifies you of new releases.
DigitalOcean also offers official Docker containers on Docker Hub. These are ideal for single use in Docker supported environments. Instructions for using the Docker image can be found on the Docker Hub page; its use is generally identical to a direct installation.
Create an access token
You must connect doctl
to your DigitalOcean account before using the tool. Authentication is persistent after installation, so you don̵
Start by logging into your DigitalOcean account. Click on the “API” link at the bottom of the sidebar. Under “Personal Access Tokens”, click the “Generate New Token” button. Name your token and enable both read and write ranges.
After your token has been created, its value will be displayed in the control panel. Save this now as it will not be possible to retrieve it later. You must create a new token if its value has been forgotten.
Connecting to your account
You can now return to your terminal. Use the generated access token to connect doctl
to your account:
doctl auth init
You will be prompted to enter the access token. Assuming the validation is successful, doctl
stores your login details. They are automatically sent with subsequent orders. Configuration files are stored in the .config/doctl
directory in your home folder.
Test your configuration
You should now be able to communicate successfully with your DigitalOcean account.
Try to run doctl account get
to check whether your account information can be retrieved.
Interact with DigitalOcean sources
doctl
lets you communicate with almost all available DigitalOcean sources. There are too many options to cover exhaustively in one article, so we’ll stick to a few commonly used commands.
doctl compute
– High level command for interacting with different types of resources. Includes droplets, domains, volumes, backups, snapshots, images, firewalls, and load balancers.doctl compute droplet
– Allows you to interact with Droplets. To attemptdoctl compute droplet list
to list all your drops, ordoctl compute droplet create --image ubuntu-20-04-x64 --size s-1vcpu-1gb --region lon1 my-droplet
to create a basic Ubuntu droplet in the LON1 data center. A variety of other subcommands provide full management options.doctl databases db
– Interaction with databases within a database cluster. Usedoctl databases db list
to retrieve existing databases anddoctl databases db create
to make. You can scale your database clusters with other related commands.doctl kubernetes
– This command namespace allows you to manage your Kubernetes clusters. A plethora of subcommands let you configure nodes, node pools, cluster versions, and container registry connections.doctl registry
– Manages your DigitalOcean Container Registry, including options to create, delete and view registries and containers. You can also call or cancel the garbage collection process to free up storage space.
A lot of functionality is available; It is advisable to consult the official documentation for the full list of commands and options. In general, every DigitalOcean API endpoint has an equivalent doctl
order.
Exploring the available commands is made easy by extensive built-in documentation. Run a top-level command, such as doctl compute
without arguments, a list of all available subcommands will be displayed. This allows quick detection of functions and means you don’t have to commit the entire list to memory.
Beside, doctl
supports auto-completion of commands within the most popular shells. Add source <(doctl completion bash)
to your ~/.profile
file is usually enough to make this possible. Deputy bash
for your own shell. Shell-specific guidelines can be found in the doctl
documents.
Using multiple accounts (contexts)
doctl
provides streamlined support for multiple DigitalOcean user accounts. You can define stand-alone authenticated "contexts" between which to switch with it --context
flag or the DIGITALOCEAN_CONTEXT
environment variable.
Use the following command to add context:
doctl auth init --context my-context
This is the same authentication command we saw earlier, this time modified every my-context
context. The context is automatically created if it does not already exist. If no context is specified, the default
context is used.
Set default configuration values
You can set default values for most options and flags using the configuration file. This is usually located on ~/.config/doctl/config.yaml
.
To define a configuration value, add it to the file using the format category.command.subcommand.flag: value
.
compute.droplet.create.size: s-1vcpu-1gb
With the above setting, all drop creations will default to the type s-1vcpu-1gb
.
Default values can be overridden at any time by passing a new value to the command line as normal.
Output formats
doctl
usually broadcasts output as human readable tables and lists. If you plan to use the tool within scripts, or want more detailed information, you can succeed --output json
to get the raw JSON from the DigitalOcean API.
You can customize the fields returned in tables with the --format
flag. Run the original command and note the column names in the output. You can pass this as a comma separated list to --format
, removing all spaces that appear in the presented names. Only the specified fields are included when you run the modified command.
Conclusion
Learning doctl
can save you time managing resources in your DigitalOcean accounts. It simplifies the use of scripts and gives you a starting point in building your own monitoring and alerting tools.
DigitalOcean regularly updates the utility. It supports almost all API operations and resource types. A notable exception is Spaces' object store; since this is compatible with Amazon S3, DigitalOcean recommends that you use an S3-specific management tool instead.
You can find complete doctl
documentation on the DigitalOcean docs site. The software is also open-source, so you can contribute your own enhancements to the GitHub repository.
Source link