DOCSEARCHbyAlgolia
Submit Docs

DropletKit Documentation

repository·main·Indexed 19 days ago

https://github.com/digitalocean/droplet_kit

A Ruby client for the DigitalOcean V2 API providing resource-oriented access to services including Droplets, Databases, CDNs, Kubernetes clusters, Firewalls, VPCs, and Container Registries. It features a client-based architecture for managing authentication, rate limiting, and resource persistence using Plain Old Ruby Objects (POROs).

Tokens
13K
Snippets
49
Records
69
Agent score
68%

What's inside DropletKit

  1. How DropletKit resources and actions work

    main

    DropletKit uses a resource-oriented design where API endpoints are accessed as methods on the client instance.

    1. Resource Access: Calling a resource method (e.g., client.droplets) returns a resource object (e.g., DropletKit::DropletResource).
    2. Lazy Execution: For actions returning multiple objects, the API request is not executed until the result is accessed (e.g., by calling .all or .first).
    3. Data Objects: The client returns Plain Old Ruby Objects (POROs) containing API data.
    4. Persistence: To save or create objects, you must instantiate the appropriate data object and pass it to the resource's action method.
    client = DropletKit::Client.new(access_token: 'YOUR_TOKEN')

# Lazy loading example
client.droplets.all.first

# Creation example
droplet = DropletKit::Droplet.new(name: 'mysite.com', region: 'nyc2', image: 'ubuntu-14-04-x64', size: 's-1vcpu-1gb')
created = client.droplets.create(droplet)

  2. Initialize a DropletKit Client

    main

    To interact with the DigitalOcean API, you must first generate an access token in the DigitalOcean control panel. Use this token to instantiate a DropletKit::Client.

    By default, the client handles burst rate limits by waiting according to the Retry-After header. It will retry a request up to three times before raising an error. You can customize this behavior using retry_max and retry_wait_min.

    require 'droplet_kit'
client = DropletKit::Client.new(access_token: 'YOUR_TOKEN')

  4. Configure automatic retries for rate-limited requests

    main

    The DropletKit::Client automatically handles 429 Too Many Requests errors using the faraday-retry middleware.

    By default, the client will retry up to 3 times. It is configured to prioritize the Retry-After header over the RateLimit-Reset header to ensure compliance with standard rate-limiting signals. You can adjust the number of retries and the minimum wait interval during client initialization.

  6. Create a Droplet with an SSH Key

    main

    To create a new Droplet and ensure you have SSH access, you should first retrieve the fingerprints of your existing SSH keys and pass them to the Droplet constructor.

    client = DropletKit::Client.new(access_token: 'YOUR_TOKEN')

# Get fingerprints of all existing SSH keys
my_ssh_keys = client.ssh_keys.all.collect {|key| key.fingerprint}

# Define the new droplet
droplet = DropletKit::Droplet.new(
  name: 'mysite.com',
  region: 'nyc2',
  image: 'ubuntu-14-04-x64',
  size: 's-1vcpu-1gb',
  ssh_keys: my_ssh_keys
)

# Create the droplet
created = client.droplets.create(droplet)

  7. Manage Snapshot resources

    main

    Use the client.snapshots resource to manage snapshots. You can list all snapshots (filtering by resource_type, e.g., 'droplet'), find a specific snapshot by ID, or delete a snapshot.

    client = DropletKit::Client.new(access_token: 'TOKEN')
client.snapshots

# Supported actions:
client.snapshots.all(resource_type: 'droplet')
client.snapshots.find(id: 'id')
client.snapshots.delete(id: 'id')

  8. Manage Volume resources

    main

    Use the client.volumes resource to manage DigitalOcean volumes. Supported actions include listing all volumes, finding a specific volume by ID, creating new volumes, managing snapshots associated with a volume, and deleting volumes.

    client = DropletKit::Client.new(access_token: 'TOKEN')
client.volumes

# Supported actions:
client.volumes.all()
client.volumes.find(id: 'id')
client.volumes.create(volume)
client.volumes.snapshots(id: 'id')
client.volumes.create_snapshot(id: 'id', name: 'snapshot-name')
client.volumes.delete(id: 'id')

  9. Manage Domains and Domain Records

    main

    Use the DomainResource to manage your domains and the DomainRecordResource to manage DNS records within those domains.

    Domain Actions:

    • all(): List all domains.
    • create(domain): Create a new domain.
    • find(name: 'name'): Find a domain by name.
    • delete(name: 'name'): Delete a domain.

    Domain Record Actions:

    • all(for_domain: 'domain_name'): List all records for a specific domain.
    • create(domain_record, for_domain: 'domain_name'): Create a new record.
    • find(for_domain: 'domain_name', id: 'id'): Find a specific record.
    • delete(for_domain: 'domain_name', id: 'id'): Delete a record.
    • update(domain_record, for_domain: 'domain_name', id: 'id'): Update an existing record.
    client = DropletKit::Client.new(access_token: 'TOKEN')

# Manage Domains
client.domains.all()
client.domains.create(domain)

# Manage Domain Records
record = DropletKit::DomainRecord.new(
  type: 'CNAME',
  name: 'www',
  data: '@',
  ttl: 1800
)
client.domain_records.create(record, for_domain: 'example.com')

  10. Manage Certificate resources

    main

    Use client.certificates to manage SSL certificates. Supported actions:

    • find(id: 'id'): Retrieve a specific certificate.
    • all(): List all certificates.
    • create(certificate): Create a new certificate.
    • delete(id: 'id'): Delete a certificate.

  11. Manage Droplet Actions

    main

    The DropletAction resource allows you to perform various operations on existing Droplets, either by targeting a specific droplet_id or by targeting all Droplets associated with a specific tag_name.

    Common actions include:

    • Power management: reboot, power_cycle, shutdown, power_off, power_on.
    • Configuration: password_reset, enable_ipv6, enable_backups, disable_backups, enable_private_networking, rename, resize.
    • Image operations: snapshot, rebuild, restore, change_kernel.

    You can also find specific actions using find or retrieve actions for a droplet/tag using action_for_id or action_for_tag.

    client = DropletKit::Client.new(access_token: 'TOKEN')
client.droplet_actions #=> DropletKit::DropletAction

# Example: Reboot a specific droplet
client.droplet_actions.reboot(droplet_id: droplet.id)

# Example: Power on all droplets with a specific tag
client.droplet_actions.power_on_for_tag(tag_name: 'web-servers')

  12. Manage Container Registry Repositories

    main

    Use the client.container_registry_repository resource to manage specific repositories within your Container Registry. You can list repositories, list tags for a repository, delete a specific tag, or delete a manifest by its digest.

    client = DropletKit::Client.new(access_token: 'TOKEN')
client.container_registry_repository

# Supported actions:
client.container_registry_repository.all(registry_name: 'registry')
client.container_registry_repository.tags(registry_name: 'registry', repository: 'repo')
client.container_registry_repository.delete_tag(registry_name: 'registry', repository: 'repo', tag: 'tag')
client.container_registry_repository.delete_manifest(registry_name: 'registry', repository: 'repo', manifest_digest: 'sha256:...')