Skip to content

Commit 10f60a0

Browse files
franckfermanfranckferman
committed
docs: add comparison with doctl and Terraform/Pulumi
1 parent 47c9d70 commit 10f60a0

2 files changed

Lines changed: 132 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
## Table of Contents
2323

2424
- [Overview](#overview)
25+
- [Why do-manager?](#why-do-manager)
2526
- [Features](#features)
2627
- [Project Structure](#project-structure)
2728
- [Installation](#installation)
@@ -48,6 +49,39 @@ Unlike a wrapper around `doctl`, `do-manager` talks directly to the DigitalOcean
4849

4950
---
5051

52+
## Why do-manager?
53+
54+
Several tools already exist to interact with DigitalOcean. Here is where `do-manager` fits:
55+
56+
| | doctl | Terraform / Pulumi | do-manager |
57+
|---|---|---|---|
58+
| **Type** | CLI binary | Infrastructure-as-Code | CLI + Go library |
59+
| **Importable as Go lib** | No | No | **Yes** |
60+
| **Requires external binary** | Yes (doctl installed) | Yes (terraform/pulumi) | No |
61+
| **State management** | No | Yes (statefile) | No |
62+
| **Parallel batch ops** | No | Partial | **Yes** |
63+
| **API coverage** | Full DO API | Full DO API | Focused (Droplets, keys, regions) |
64+
| **Learning curve** | Low | High (HCL / SDK) | Low |
65+
| **Embed in another Go project** | Subprocess + parsing | SDK only | `import "pkg/droplet"` |
66+
67+
### vs doctl
68+
69+
`doctl` is the official DigitalOcean CLI. It covers the entire API surface and is the right tool for manual operations from the terminal.
70+
71+
`do-manager` targets a different use case: **embedding cloud provisioning inside another Go program**. Instead of shelling out to `doctl` and parsing its output, you import `pkg/droplet` and call typed Go functions directly. No binary dependency, no version mismatch, no fragile string parsing.
72+
73+
### vs Terraform / Pulumi
74+
75+
Terraform and Pulumi are full infrastructure-as-code platforms. They manage state, handle drift detection, and orchestrate dozens of providers. That power comes with significant overhead: HCL or SDK boilerplate, a statefile to manage, and a heavy binary to ship.
76+
77+
`do-manager` has no concept of state. It is a thin, focused layer over the DigitalOcean API for programs that need to **provision and destroy Droplets programmatically** without pulling in an IaC framework.
78+
79+
### The one-liner
80+
81+
> Use `doctl` when you work from the terminal. Use `do-manager` when you build a Go tool that needs to manage Droplets.
82+
83+
---
84+
5185
## Features
5286

5387
| Area | Supported operations |

‎docs/index.html‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -457,6 +457,7 @@
457457
<nav>
458458
<span class="nav-brand">do-manager</span>
459459
<ul class="nav-links">
460+
<li><a href="#why">Why?</a></li>
460461
<li><a href="#install">Install</a></li>
461462
<li><a href="#config">Config</a></li>
462463
<li><a href="#droplets">Droplets</a></li>
@@ -474,6 +475,7 @@
474475
<aside>
475476
<div class="sidebar-section">
476477
<div class="sidebar-title">Getting Started</div>
478+
<a class="sidebar-link" href="#why">Why do-manager?</a>
477479
<a class="sidebar-link" href="#install">Installation</a>
478480
<a class="sidebar-link" href="#config">Configuration</a>
479481
</div>
@@ -560,6 +562,102 @@ <h3>No doctl needed</h3>
560562

561563
<hr />
562564

565+
<!-- WHY -->
566+
<section id="why">
567+
<h2>Why do-manager?</h2>
568+
<p>Several tools already exist to manage DigitalOcean infrastructure. Here is where <code>do-manager</code> fits.</p>
569+
570+
<table class="ref-table">
571+
<thead>
572+
<tr>
573+
<th></th>
574+
<th>doctl</th>
575+
<th>Terraform / Pulumi</th>
576+
<th>do-manager</th>
577+
</tr>
578+
</thead>
579+
<tbody>
580+
<tr>
581+
<td><strong>Type</strong></td>
582+
<td>CLI binary</td>
583+
<td>Infrastructure-as-Code</td>
584+
<td>CLI + Go library</td>
585+
</tr>
586+
<tr>
587+
<td><strong>Importable as Go lib</strong></td>
588+
<td><span style="color:var(--red)">No</span></td>
589+
<td><span style="color:var(--red)">No</span></td>
590+
<td><span style="color:var(--green)">Yes</span></td>
591+
</tr>
592+
<tr>
593+
<td><strong>Requires external binary</strong></td>
594+
<td><span style="color:var(--red)">Yes (doctl)</span></td>
595+
<td><span style="color:var(--red)">Yes (terraform/pulumi)</span></td>
596+
<td><span style="color:var(--green)">No</span></td>
597+
</tr>
598+
<tr>
599+
<td><strong>State management</strong></td>
600+
<td>No</td>
601+
<td><span style="color:var(--yellow)">Yes (statefile)</span></td>
602+
<td>No</td>
603+
</tr>
604+
<tr>
605+
<td><strong>Parallel batch ops</strong></td>
606+
<td><span style="color:var(--red)">No</span></td>
607+
<td>Partial</td>
608+
<td><span style="color:var(--green)">Yes</span></td>
609+
</tr>
610+
<tr>
611+
<td><strong>Embed in a Go project</strong></td>
612+
<td><span style="color:var(--red)">Subprocess + parsing</span></td>
613+
<td>SDK only</td>
614+
<td><span style="color:var(--green)"><code>import "pkg/droplet"</code></span></td>
615+
</tr>
616+
<tr>
617+
<td><strong>Learning curve</strong></td>
618+
<td>Low</td>
619+
<td>High (HCL / SDK)</td>
620+
<td>Low</td>
621+
</tr>
622+
<tr>
623+
<td><strong>API coverage</strong></td>
624+
<td>Full DO API</td>
625+
<td>Full DO API</td>
626+
<td>Focused (Droplets, keys, regions)</td>
627+
</tr>
628+
</tbody>
629+
</table>
630+
631+
<h3>vs doctl</h3>
632+
<p>
633+
<a href="https://github.com/digitalocean/doctl">doctl</a> is the official DigitalOcean CLI.
634+
It covers the entire API surface and is the right tool for manual operations from the terminal.
635+
</p>
636+
<p>
637+
<code>do-manager</code> targets a different use case: <strong style="color:var(--white)">embedding cloud provisioning inside another Go program</strong>.
638+
Instead of shelling out to <code>doctl</code> and parsing its output, you import <code>pkg/droplet</code>
639+
and call typed Go functions directly. No binary dependency, no version mismatch, no fragile string parsing.
640+
</p>
641+
642+
<h3>vs Terraform / Pulumi</h3>
643+
<p>
644+
Terraform and Pulumi are full IaC platforms. They manage state, handle drift detection, and orchestrate dozens of providers.
645+
That power comes with significant overhead: HCL or SDK boilerplate, a statefile to maintain, and a heavy binary to ship.
646+
</p>
647+
<p>
648+
<code>do-manager</code> has no concept of state. It is a thin, focused layer over the DigitalOcean API
649+
for programs that need to <strong style="color:var(--white)">provision and destroy Droplets programmatically</strong>
650+
without pulling in an IaC framework.
651+
</p>
652+
653+
<div class="callout">
654+
<strong>The one-liner:</strong> use <code>doctl</code> when you work from the terminal.
655+
Use <code>do-manager</code> when you build a Go tool that needs to manage Droplets.
656+
</div>
657+
</section>
658+
659+
<hr />
660+
563661
<!-- INSTALL -->
564662
<section id="install">
565663
<h2>Installation</h2>

0 commit comments

Comments
 (0)