argotails

README

Argotails

Synchronize your remote ArgoCD clusters with Tailscale devices in real time

---

📚 Table of Contents

• About
  • Features
• How to use Argotails
  • Prerequisites
  • Setup Guide
    • Creating Tailscale OAuth Credentials
    • Setting Up the Webhook (optional, but recommended)
  • Deploying with Kustomize
    • Creating the Tailscale Secret
    • Basic Deployment Example
    • Deployment with Webhook Support
• Configuration Reference
• Troubleshooting & FAQ
• Contribution Guidelines
• License

---

ℹ️ About

Argotails is a Kubernetes controller that synchronizes Tailscale devices with ArgoCD clusters. It ensures your cluster secrets remain up-to-date as your Tailscale environment changes. This tool is ideal for teams that want to automate secret updates without manual intervention.

[!IMPORTANT] Argotails is designed to work alongside the Tailscale Kubernetes API proxy. Without this integration, ArgoCD will not be able to access the remote Kubernetes API, making all secrets managed by Argotails useless.

✨ Features

• Real-time Synchronization: Automatically update ArgoCD secrets when Tailscale devices are added or removed.
• Multi-cluster ArgoCD Support: Create Kubernetes services with Tailscale annotations for the official Tailscale multi-cluster ArgoCD solution.
• Customizable Filters: Use regular expressions to determine which Tailscale devices should be synchronized.
• Flexible Deployment: Deploy Argotails on any Kubernetes cluster with ArgoCD installed.
• Webhook Integration: Optional webhook support for instant updates using Tailscale Funnel or your preferred method.
• Backward Compatibility: Existing sidecar approach continues to work unchanged alongside the new service creation feature.

---

🚀 How to use Argotails

🔑 Prerequisites

Before deploying Argotails, ensure you have:

• A running Kubernetes cluster with ArgoCD installed
• A Tailscale account with admin privileges
• A Tailscale network configured to use the Tailscale Kubernetes API proxy
• kubectl configured to access your cluster
• kustomize (or use kubectl built-in kustomize support)

For further guidance on setting up Kubernetes and ArgoCD, refer to the official Kubernetes documentation and ArgoCD docs.

⚙️ Setup Guide

1. Creating Tailscale OAuth Credentials

1. Log in to Tailscale:
   Go to the Tailscale Admin Console.

2. Generate OAuth Credentials:

   • Navigate to Settings > Keys.
   • Click Generate OAuth client credentials.
   • Provide a descriptive name (e.g., "Argotails Integration").
   • Enable Read access on the Devices / Core scope.
   • Save your client ID and client secret securely.

   Tip: Refer to Tailscale’s documentation for a detailed explanation of OAuth tokens and scopes.

2. Setting Up the Webhook (optional, but recommended)

If you want real-time updates via webhooks:

1. Configure the Webhook:
   • In the Tailscale Admin Console, navigate to Settings > Webhooks.
   • Click Add endpoint.
   • Enter a name such as "Argotails Device Updates".
   • Set the endpoint URL to your Argotails webhook endpoint (e.g., https://argotails.your-domain.com/webhook).
   • Select only the nodeCreated and nodeDeleted events.
   • Copy and securely store the generated webhook secret for later use.

📦 Deploying with Kustomize

[!NOTE] No Helm chart is available for Argotails because they require too much maintenance for a simple project like this. Kustomize is the recommended way to deploy Argotails.

Argotails is deployable via Kustomize. Follow these steps based on your chosen deployment mode.

1. Creating the Tailscale Secret

[!TIP] All example commands assume you have installed ArgoCD in the argocd namespace. Adjust the namespace if you have a different setup.

Create a Kubernetes secret with your Tailscale OAuth credentials (and webhook secret if using the webhook):

# Replace 'tskey-auth-xxxxxxxxxxxx' with your actual Tailscale auth key.
kubectl create secret generic tailscale-secrets \
  --namespace argocd \
  --from-literal=authkey='tskey-auth-xxxxxxxxxxxx' \
  --dry-run=client -o yaml | kubectl apply -f -

If using the webhook feature, patch the secret to add the webhook secret:

kubectl patch secret tailscale-secrets \
  --namespace argocd \
  --type merge \
  --patch '{"data":{"webhook_secret":"tskey-webhook--xxxxxxxxxxxx"}}'

2. Basic Deployment Example

Create a kustomization.yaml file to deploy Argotails using the default manifests:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: argocd

resources:
  - https://github.com/chezmoidotsh/argotails//deploy/manifests/default?ref=main

patches:
  - patch: |
      - op: replace
        path: /spec/template/spec/containers/0/env/0/value
        value: my-tailnet.ts.net
    target:
      name: argotails
      kind: Deployment

[!TIP]

• Replace my-tailnet.ts.net with your actual Tailscale tailnet.
• Adjust patch values for other environments as needed.

3. Deployment with Webhook Support

For deployments that require webhook support via Tailscale Funnel, use the following kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: argocd

resources:
  - https://github.com/chezmoidotsh/argotails//deploy/manifests/with-webhook-funnel?ref=main

patches:
  - patch: |
      - op: replace
        path: /spec/template/spec/containers/0/env/0/value
        value: my-tailnet.ts.net
    target:
      name: argotails
      kind: Deployment

It will create a new Tailscale device with the name argotails available PUBLICLY on the internet; https://argotails.your-tailnet.ts.net will be the URL to access the webhook.

[!CAUTION] Security Warning: Exposing the webhook publicly can lead to security vulnerabilities. However, it is the only way to receive real-time updates from Tailscale. Everything has been done to secure the webhook and the only thing it does is to update the Kubernetes secret with the new Tailscale device... but be careful and don't expose it if some delay is acceptable for you.

---

📝 Configuration Reference

Argotails is highly configurable via flags and environment variables. Here’s an overview:

Usage: argotails run --ts.tailnet=TAILSCALE_TAILNET --ts.authkey=TAILSCALE_AUTH_KEY [flags]

Run the ArgoCD Tailscale integration controller.

Flags:
  -h, --help                      Show context-sensitive help.

      --reconcile.interval=30s    Time between two Tailscale devices and ArgoCD cluster secrets reconciliation ($RECONCILE_INTERVAL).

Tailscale flags
  --ts.base-url=https://api.tailscale.com                   Tailscale API base URL ($TAILSCALE_BASE_URL).
  --ts.tailnet=TAILSCALE_TAILNET                            Tailscale network name ($TAILSCALE_TAILNET).
  --ts.authkey=TAILSCALE_AUTH_KEY                           Tailscale OAuth key ($TAILSCALE_AUTH_KEY).
  --ts.authkey-file=TAILSCALE_AUTH_KEY_FILE                 Path to the file containing the Tailscale OAuth key ($TAILSCALE_AUTH_KEY_FILE).
  --ts.device-filter=PATTERN,...                            List of regular expressions to filter the Tailscale devices based on their tags.
  --ts.webhook.enable                                       Enable the Tailscale webhook handler ($TAILSCALE_WEBHOOK_ENABLE).
  --ts.webhook.port=3000                                    Tailscale webhook port ($TAILSCALE_WEBHOOK_PORT).
  --ts.webhook.secret=TAILSCALE_WEBHOOK_SECRET              Tailscale webhook secret ($TAILSCALE_WEBHOOK_SECRET).
  --ts.webhook.secret-file=TAILSCALE_WEBHOOK_SECRET_FILE    Path to the file containing the Tailscale webhook secret ($TAILSCALE_WEBHOOK_SECRET_FILE).

Service flags
  --service.create                   Create Kubernetes services with Tailscale annotations for multi-cluster ArgoCD support ($CREATE_SERVICE).
  --service.proxy-class=STRING       ProxyClass to use for Tailscale services (optional) ($SERVICE_PROXY_CLASS).

ArgoCD flags
  --argocd.namespace=STRING    Namespace where ArgoCD is installed (if the controller is runned outside a cluster) ($ARGOCD_NAMESPACE).

Log flags
  --log.devel          Enable development logging ($LOG_DEVEL).
  --log.v=2            Log verbosity level ($LOG_VERBOSITY).
  --log.format=json    Log encoding format, either 'json' or 'console' ($LOG_FORMAT).

[!TIP] You can also load credentials from files using the --ts.authkey-file and --ts.webhook.secret-file flags.

Service Creation for Multi-cluster ArgoCD

Argotails supports the official Tailscale multi-cluster ArgoCD solution by creating Kubernetes services with Tailscale annotations. When enabled, Argotails creates services alongside secrets, allowing the Tailscale Kubernetes Operator to manage dedicated proxy pods for each cluster.

When to Use Service Creation:

• You want to use the official Tailscale multi-cluster ArgoCD approach
• You prefer dedicated proxy pods over sidecar containers
• You need more granular control over network policies and resource allocation
• You want to leverage Tailscale ProxyClass configurations

Service Creation Behavior:

• Services are created with tailscale.com/tailnet-fqdn annotation set to the device hostname
• Optional tailscale.com/proxy-class annotation when --service.proxy-class is specified
• Services are managed alongside secrets - created, updated, and deleted in sync with device changes
• All device tags and metadata are preserved in service labels for filtering and identification

Example Usage:

argotails run \
  --ts.tailnet=my-tailnet.ts.net \
  --ts.authkey=tskey-auth-xxxxxxxxxxxx \
  --service.create \
  --service.proxy-class=my-proxy-class

[!NOTE] Service creation is disabled by default to maintain backward compatibility. Existing deployments will continue to work unchanged unless explicitly enabled.

---

🔧 Troubleshooting & FAQ

[!TIP] You can use the --log.v flag to increase verbosity for debugging.

Common Issues and Solutions

• Pods Not Starting:
  Verify that your Kubernetes secret is correctly created and that your environment variables match your OAuth credentials.

• Synchronization Failures:
  Check the logs:

  kubectl logs -n argocd -l app.kubernetes.io/name=argotails
  

  Confirm that the webhook (if enabled) is correctly receiving events.

• Webhook Validation Errors:
  Ensure that the webhook secret in Tailscale and in your Kubernetes secret are identical.

---

🤝 Contribution Guidelines

Contributions are welcome! Please review our CONTRIBUTING.md for detailed guidelines on how to contribute, including coding standards, pull request instructions, and testing requirements.

---

📜 License

Argotails is distributed under the MIT license. See the LICENSE file for further details.