Secure Your Swarm: Laying the Foundation with mTLS in v1.5.0

Security shouldn't be a trade-off for simplicity. In the world of Docker Swarm, managing secure access often involves a complex dance of manual certificate generation or relying on insecure plain-text connections.

With the release of SwarmCLI v1.5.0, we’re laying the foundation to change that. We’ve introduced the open-source SwarmCLI Proxy, a dedicated security layer that brings mTLS authentication and an internal Certificate Authority to your cluster. While configuring the initial certificates still involves some boilerplate in the Community Edition, this release provides a robust, hardened endpoint that sets the stage for future RBAC (Role-Based Access Control) and multi-user onboarding features.

The Problem: The "Open Door" Policy

By default, exposing the Docker Engine API over a network is risky. Standard TCP connections are unencrypted, and without proper authentication, anyone with network access can take control of your cluster. Implementing Mutual TLS (mTLS) is the gold standard, but setting it up—and more importantly, managing user certificates—is often too much friction for busy teams.

The Solution: A Hardened Security Layer

SwarmCLI v1.5.0 officially integrates the swarmcli-rbac-proxy. Deploying this stack inside your Swarm establishes a fortified entry point that manages authenticated traffic before it ever touches your Docker Engine.

How it works: Seeding the Infrastructure

By configuring your TLS keys and declaring PROXY_SEED_USERNAME during your docker stack deploy, the proxy is able to dynamically seed your environment:

Internal CA: By mounting a CA private key, the proxy can act as its own Certificate Authority to automatically issue and manage mTLS client certificates for your users.
State Management: The seeded admin user and ensuing credentials are automatically persisted securely into the proxy's internal SQLite database.
Local Execution: Using the internal swcproxy admin CLI within the proxy container, administrators can effortlessly add users and manage roles.

The Foundation for Teams

While the current version of the proxy is focused on securing the primary administrative connection, we’ve built it with the future in mind. The infrastructure we’re deploying today lays the groundwork for the upcoming RBAC system.

Looking Ahead: The Onboarding Flow

In future updates, adding new users will be as simple as generating a one-time token. Here’s a sneak peek at the workflow we're currently building:

1. The Conceptual Flow

The admin will generate a secure, one-time token. The user will then pull their pre-configured Docker context directly from the proxy using that token.

sequenceDiagram
    participant Admin
    participant Proxy
    participant User
    Admin->>Proxy: swcproxy user add alice
    Proxy-->>Admin: One-time Token + URL
    Admin->>User: Share Token
    User->>Proxy: GET /api/v1/onboard/<token>
    Proxy-->>User: alice.tar (Certs + Config)
    User->>User: docker context import alice.tar

2. In the Terminal (Developer Preview)

Here is a look at the planned implementation currently in development.

Admin Side:

# Inside the proxy container or via SwarmCLI
swcproxy user add alice

# Output:
# User 'alice' created.
# Share this command with the user:
# curl -k https://swarm.example.com:2376/api/v1/onboard/abc-123-xyz -o alice.tar

User Side:

# Download the context
curl -k https://swarm.example.com:2376/api/v1/onboard/abc-123-xyz -o alice.tar

# Import and use
docker context import alice alice.tar
docker --context alice ps

Architecture: Hardened by Design

The new architecture uses a dual-listener approach within the rbac-proxy container:

Internal (127.0.0.1:2375): Plain TCP for administrative tasks within the container.
External (0.0.0.0:2376): Full mTLS verification for all remote connections.

Everything is backed by a persistent SQLite store (with optional PostgreSQL support for high-availability clusters), ensuring your foundational RBAC data, onboarding tokens, and roles survive container restarts.

Protection for Your Infrastructure

We've also added "Infrastructure Protection" guards to prevent accidental deletion of critical networking components like the swarmcli-agent-net. SwarmCLI v1.5.0 isn't just about making Swarm easier to use—it's about making it safer to run.

Also in v1.5.0

While the new mTLS proxy is the star of this release, v1.5.0 also brings several quality-of-life improvements to the core CLI experience:

New Exit Key: To prevent accidental app exits, the exit shortcut has been changed from q to Ctrl+Q.
Export Stack YAML: You can now save a deployed stack's YAML directly back to your local filesystem.
Enhanced Inspect: Stack inspect now accurately shows per-service secrets and configs.
Improved Reliability: We've added robust timeouts to all Docker API calls, significantly reducing redundant requests.

Get Started

Ready to secure your cluster? Update to v1.5.0 today.

Detailed documentation and the full source code are available on our GitHub repository.

For a more comprehensive look at the proxy's technical architecture, check out our SwarmCLI Proxy Product Deep Dive.

Why SwarmCLI?

By 2026, we noticed a gap. Docker Swarm was rock solid, but the management tooling felt stuck in 2017. SwarmCLI bridges that gap with:

Real-time Health: Stop guessing which node is throttled.
Atomic Secret Sync: One-command .env to Raft encryption.
Edge-Optimized: Built in Go for zero-overhead on ARM/RPi5 devices.

推荐订阅源

DEV Community