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 |
upwindctl configures workloads to report to the US region by default. If your Upwind tenant is in another region, add --region with your region (for example eu or me) to the instrument and instrument-appservice commands on this page.
Install upwindctl
To install upwindctl, see Install upwindctl.
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 \
--tracer-image public.ecr.aws/upwindsecurity/images/tracer:0.10.2 \
--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 \
--tracer-image public.ecr.aws/upwindsecurity/images/tracer:0.10.2 \
--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 | Tracer image. The default is an older tracer release, so pass the current image as the examples on this page do | public.ecr.aws/upwindsecurity/images/tracer:0.9.0 | No |
--api-security | Enable API security reporting | false | No |
--region | Upwind region your tenant is in, for example eu or me | us | 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.
The vault must be in the same resource group as the Container App and contain two secrets named upwind-client-id and upwind-client-secret. To create a vault with these secrets, run:
upwindctl azure key-vault \
--subscription-id <SUBSCRIPTION_ID> \
--resource-group <RESOURCE_GROUP> \
--location <AZURE_LOCATION> \
--name <KEY_VAULT_NAME> \
--client-id <UPWIND_CLIENT_ID> \
--client-secret <UPWIND_CLIENT_SECRET>
Then instrument the Container App with --key-vault-name:
upwindctl azure instrument \
--tracer-image public.ecr.aws/upwindsecurity/images/tracer:0.10.2 \
--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 \
--tracer-image public.ecr.aws/upwindsecurity/images/tracer:0.10.2 \
--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 \
--tracer-image public.ecr.aws/upwindsecurity/images/tracer:0.10.2 \
--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 the binary from. The default is an older tracer release, so pass the current image as the examples on this page do | public.ecr.aws/upwindsecurity/images/tracer:0.9.0 | 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 |
--region | Upwind region your tenant is in, for example eu or me | us | No |
Using Key Vault for Credentials
upwindctl azure instrument-appservice \
--tracer-image public.ecr.aws/upwindsecurity/images/tracer:0.10.2 \
--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 | Set to true to enable direct backend reporting |
UPWIND_TRACER_REGION | Upwind region from --region, for example eu or me. Not set for the default us region. The tracer derives the authentication, registration and reporting endpoints from this value |
UPWIND_TRACER_AUTH_CLIENT_ID | OAuth client ID. On Container Apps, read from the upwind-client-id container app secret in both direct credentials and Key Vault mode. On App Service, set in direct credentials mode |
UPWIND_TRACER_AUTH_CLIENT_SECRET | OAuth client secret. On Container Apps, read from the upwind-client-secret container app secret in both direct credentials and Key Vault mode. On App Service, set in direct credentials mode |
UPWIND_KEY_VAULT_URL | Key Vault URL (App Service in Key Vault mode) |
UPWIND_TRACER_ENABLE_REGISTRATION | Set to true (App Service) |
UPWIND_CLOUD_PROVIDER | Set to azure |
UPWIND_CLOUD_ACCOUNT_ID | Azure subscription ID |
UPWIND_TRACER_ZONE | Azure location of the Container App (Container Apps) |
CONTAINER_APP_RESOURCE_GROUP | Resource group of the Container App (Container Apps) |
CONTAINER_APP_ENVIRONMENT_NAME | Container App Environment name (Container Apps) |
UPWIND_AZURE_SITE_NAME | App Service name (App Service) |
UPWIND_AZURE_RESOURCE_GROUP | Resource group of the App Service (App Service) |
UPWIND_TRACER_EXTENDED_SYSCALLS | Extended syscall tracing (when --api-security is set) |
UPWIND_TRACER_REPORT_API_CATALOG | API catalog reporting. Set when --api-security is set on Container Apps, and always on App Service |
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
--regionmatches the region of your Upwind tenant - Check that the workload has outbound internet access to the Upwind backend
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)