Workload Configuration (Direct to Backend)
In environments where a cluster manager is not deployed, workloads can be configured to report directly to the Upwind backend. This approach uses the upwindctl CLI tool to instrument Azure Container Apps and App Service workloads.
Prerequisites
Before configuring workloads, you need the following:
| Value | Description | How to Get |
|---|---|---|
| Upwind Client ID | OAuth client ID for backend authentication | Upwind Console → Settings → API Credentials |
| Upwind Client Secret | OAuth client secret for backend authentication | Upwind Console → Settings → API Credentials |
| Azure Subscription ID | The Azure subscription containing your workloads | Azure Portal → Subscriptions |
Install upwindctl
Install using the official install script:
curl -s https://get.upwind.io/upwindctl.sh | sh
Verify the installation:
upwindctl --help
Azure Container Apps
Instrument with upwindctl
The upwindctl azure instrument command adds the Upwind tracer to Azure Container Apps. It configures an init container to copy the tracer binary, prefixes the application command, and sets the required environment variables.
Single Container App
upwindctl azure instrument \
--subscription-id <SUBSCRIPTION_ID> \
--resource-group <RESOURCE_GROUP> \
--container-app <CONTAINER_APP_NAME> \
--client-id <UPWIND_CLIENT_ID> \
--client-secret <UPWIND_CLIENT_SECRET>
Batch Instrumentation (All Apps in an Environment)
To instrument all container apps within a Container App Environment:
upwindctl azure instrument \
--subscription-id <SUBSCRIPTION_ID> \
--resource-group <RESOURCE_GROUP> \
--container-app-env <CONTAINER_APP_ENVIRONMENT_NAME> \
--client-id <UPWIND_CLIENT_ID> \
--client-secret <UPWIND_CLIENT_SECRET>
This will instrument all container apps in the specified environment. The command will:
- List all container apps in the environment
- Instrument each app sequentially
- Provide progress updates and a summary of successes/failures
- Continue instrumenting remaining apps even if some fail
Instrumenting a Container App does not automatically apply to new containers added after the initial instrumentation. If you add new containers to an already-instrumented Container App, you must re-run the upwindctl azure instrument command to instrument them.
Flags
| Flag | Description | Default | Required |
|---|---|---|---|
--subscription-id | Azure subscription ID | - | Yes |
--resource-group | Azure resource group name | - | Yes |
--container-app | Container App name (single app mode) | - | One of --container-app or --container-app-env |
--container-app-env | Container App Environment name (batch mode) | - | One of --container-app or --container-app-env |
--client-id | Upwind OAuth client ID | - | One of credential modes |
--client-secret | Upwind OAuth client secret | - | One of credential modes |
--key-vault-name | Azure Key Vault name (alternative to direct credentials) | - | One of credential modes |
--container | Target container name. If not specified, all containers in the Container App will be instrumented | All containers | No |
--tracer-image | Custom tracer image | public.ecr.aws/upwindsecurity/images/tracer:0.7.16 | No |
--api-security | Enable API security reporting | false | No |
--auth-endpoint | Custom OAuth token endpoint | https://oauth.upwind.io/oauth/token | No |
--backend-api-host | Custom backend API host | https://agent.upwind.io | No |
Using Key Vault for Credentials
Instead of passing credentials directly, you can store them in an Azure Key Vault. The upwindctl tool will configure the Container App to read credentials from the vault at runtime using its managed identity.
upwindctl azure instrument \
--subscription-id <SUBSCRIPTION_ID> \
--resource-group <RESOURCE_GROUP> \
--container-app <CONTAINER_APP_NAME> \
--key-vault-name <KEY_VAULT_NAME>
Deinstrument
To remove the Upwind tracer from a Container App:
upwindctl azure deinstrument \
--subscription-id <SUBSCRIPTION_ID> \
--resource-group <RESOURCE_GROUP> \
--container-app <CONTAINER_APP_NAME>
Azure App Service
The upwindctl azure instrument-appservice command instruments Azure App Services with the Upwind tracer. The tracer binary is automatically extracted from the Docker image and uploaded to the App Service. The tool then sets the required environment variables and prefixes the startup command.
Instrument with upwindctl
Single App Service
upwindctl azure instrument-appservice \
--subscription-id <SUBSCRIPTION_ID> \
--resource-group <RESOURCE_GROUP> \
--app-name <APP_SERVICE_NAME> \
--client-id <UPWIND_CLIENT_ID> \
--client-secret <UPWIND_CLIENT_SECRET>
Batch Instrumentation (All Apps in a Service Plan)
To instrument all app services within an App Service Plan:
upwindctl azure instrument-appservice \
--subscription-id <SUBSCRIPTION_ID> \
--resource-group <RESOURCE_GROUP> \
--app-service-plan <APP_SERVICE_PLAN_NAME> \
--client-id <UPWIND_CLIENT_ID> \
--client-secret <UPWIND_CLIENT_SECRET>
This will instrument all app services in the specified plan. The command will:
- List all app services in the plan
- Extract the tracer binary once (shared across all apps for efficiency)
- Instrument each app sequentially
- Provide progress updates and a summary of successes/failures
- Continue instrumenting remaining apps even if some fail
Flags
| Flag | Description | Default | Required |
|---|---|---|---|
--subscription-id | Azure subscription ID | - | Yes |
--resource-group | Azure resource group name | - | Yes |
--app-name | App Service name (single app mode) | - | One of --app-name or --app-service-plan |
--app-service-plan | App Service Plan name (batch mode) | - | One of --app-name or --app-service-plan |
--client-id | Upwind OAuth client ID | - | One of credential modes |
--client-secret | Upwind OAuth client secret | - | One of credential modes |
--key-vault-name | Azure Key Vault name (alternative to direct credentials) | - | One of credential modes |
--tracer-image | Tracer image to extract binary from | public.ecr.aws/upwindsecurity/images/tracer:0.7.16 | No |
--tracer-path | Path where tracer binary will be uploaded | /home/upwind-tracer | No |
--api-security | Enable API security reporting | false | No |
--process-report-interval | Process report interval | 1m | No |
--auth-endpoint | Custom OAuth token endpoint | https://oauth.upwind.io/oauth/token | No |
--backend-api-host | Custom backend API host | https://agent.upwind.io | No |
--dev | Use Upwind dev environment | false | No |
Using Key Vault for Credentials
upwindctl azure instrument-appservice \
--subscription-id <SUBSCRIPTION_ID> \
--resource-group <RESOURCE_GROUP> \
--app-name <APP_SERVICE_NAME> \
--key-vault-name <KEY_VAULT_NAME>
Deinstrument
To remove the Upwind tracer from an App Service:
upwindctl azure deinstrument-appservice \
--subscription-id <SUBSCRIPTION_ID> \
--resource-group <RESOURCE_GROUP> \
--app-name <APP_SERVICE_NAME>
Environment Variables
When using direct-to-backend mode, upwindctl configures the following environment variables:
| Variable | Description |
|---|---|
UPWIND_TRACER_REPORT_TO_BACKEND | Enables direct backend reporting |
UPWIND_TRACER_AUTH_ENDPOINT | OAuth token endpoint |
UPWIND_TRACER_BACKEND_API_HOST | Upwind backend API host |
UPWIND_TRACER_REGISTRATION_HOST | Upwind registration host |
UPWIND_TRACER_AUTH_CLIENT_ID | OAuth client ID (when using direct credentials) |
UPWIND_TRACER_AUTH_CLIENT_SECRET | OAuth client secret (when using direct credentials) |
UPWIND_KEY_VAULT_URL | Key Vault URL (when using Key Vault mode) |
UPWIND_CLOUD_PROVIDER | Set to azure |
UPWIND_CLOUD_ACCOUNT_ID | Azure subscription ID |
UPWIND_TRACER_EXTENDED_SYSCALLS | Extended syscall tracing (when --api-security is set) |
UPWIND_TRACER_REPORT_API_CATALOG | API catalog reporting (when --api-security is set) |
Batch Operations
Benefits of Batch Mode
- Efficiency: Instrument multiple workloads with a single command
- Consistency: Apply the same configuration across all workloads in an environment or plan
- Time-saving: Especially useful for environments with many workloads
- Resilience: Continues instrumenting even if some workloads fail
Batch Progress Reporting
During batch instrumentation, the tool provides:
- Total number of workloads found
- Progress indicators (
[1/5],[2/5], etc.) - Success/failure status for each workload
- Final summary with success and failure counts
Example Batch Output
Found 3 container app(s) to instrument:
- app-one
- app-two
- app-three
[1/3] Instrumenting container app 'app-one'...
SUCCESS: 'app-one' instrumented successfully
[2/3] Instrumenting container app 'app-two'...
ERROR: Failed to instrument 'app-two': container app not found
[3/3] Instrumenting container app 'app-three'...
SUCCESS: 'app-three' instrumented successfully
========================================
Batch instrumentation complete:
Total: 3
Success: 2
Failed: 1
Troubleshooting
Issue: Tracer fails to authenticate with backend
- Verify the client ID and secret are correct
- If using Key Vault, ensure the workload's managed identity has
Getaccess to secrets in the vault - Check that the
--auth-endpointis reachable from the workload
Issue: upwindctl fails with permission errors
- Ensure you are logged in with
az loginand have Contributor role on the resource group - For Key Vault mode, ensure you have permissions to create and manage Key Vault access policies
Issue: Batch instrumentation fails for some workloads
- Review the error messages for each failed workload
- Common causes include:
- Workload is in a stopped or transitioning state
- Insufficient permissions on specific workloads
- Network connectivity issues
- The command continues processing remaining workloads, so successful instrumentations are preserved
- You can re-run the batch command - already instrumented workloads will be updated (idempotent operation)