Skip to content

using-dry-run.md

Latest commit

 

History

History
224 lines (146 loc) · 7.79 KB

using-dry-run.md

File metadata and controls

224 lines (146 loc) · 7.79 KB

Using Dry Run

The Auth0 Deploy CLI supports a "dry run" mode that allows you to preview all potential changes to your Auth0 tenant without actually applying them. This feature provides a safety net for validating configurations and understanding the impact of deployments before they occur.

Discussions thread

Usage

Command Line Interface

Add the --dry-run flag to your import command:

a0deploy import --config_file=config.json --input_file=./tenant.yaml --dry-run

Or use the shorter form:

a0deploy import -c config.json -i ./tenant-directory --dry-run

Node Module

Set the AUTH0_DRY_RUN configuration property to true:

import { deploy } from 'auth0-deploy-cli';

deploy({
  input_file: './local/tenant.yaml',
  config: {
    AUTH0_DOMAIN: process.env.AUTH0_DOMAIN,
    AUTH0_CLIENT_ID: process.env.AUTH0_CLIENT_ID,
    AUTH0_CLIENT_SECRET: process.env.AUTH0_CLIENT_SECRET,
    AUTH0_DRY_RUN: true,
  },
})
  .then(() => {
    console.log('Dry run completed successfully');
  })
  .catch((err) => {
    console.log('Error during dry run:', err);
  });

Note: To get the interactive menu when using the Node module, also set AUTH0_DRY_RUN_INTERACTIVE: true.

To show the preview and then apply without prompting when using the Node module, set AUTH0_DRY_RUN_APPLY: true alongside AUTH0_DRY_RUN: true.

Environment Variable

You can also enable dry run mode using an environment variable:

export AUTH0_DRY_RUN=true
a0deploy import -c config.json -i ./tenant.yaml

CI/CD Usage

By default, --dry-run is non-interactive and safe for CI pipelines.

Preview Only

Shows the plan and exits without applying changes:

a0deploy import -c config.json -i tenant.yaml --dry-run

GitHub Actions:

- name: Preview Auth0 changes
  run: a0deploy import -c config.json -i tenant.yaml --dry-run

Deployment with Visibility

Show the plan and apply without prompting:

a0deploy import -c config.json -i tenant.yaml --dry-run --apply

Interactive Review (Manual Deployments)

Add --interactive to get the menu (apply / export to file / exit):

a0deploy import -c config.json -i tenant.yaml --dry-run --interactive

Understanding the Output

Dry run mode provides a detailed preview of all proposed changes in a table format:

Auth0 Deploy CLI - Dry Run Preview

Tenant: example-tenant.auth0.com
Input: local/tenant.yaml

Simulating deployment... The following changes are proposed:

┌─────────────┬─────────┬──────────────────────────────────┐
│ Resource    │ Status  │ Name / Identifier                │
├─────────────┼─────────┼──────────────────────────────────┤
│ Actions     │ CREATE  │ Post-Login User Enrichment       │
│             │ CREATE  │ Pre-Registration Validation      │
│             │ DELETE* │ Deprecated Action                │
│ Clients     │ CREATE  │ New SPA Application              │
│             │ UPDATE  │ Existing M2M Application         │
│ Connections │ UPDATE  │ Username-Password-Authentication │
└─────────────┴─────────┴──────────────────────────────────┘

* Requires AUTH0_ALLOW_DELETE to be enabled

Dry Run completed successfully. No changes have been made to your Auth0 tenant.

┌ dry-run
│
◆ What would you like to do?
│ ○ Apply changes
│ ○ Export changes in a file (No Apply)
│ ○ Exit
└

Interactive Options

After displaying the dry run preview, the CLI presents interactive options:

  • Apply changes: Proceed to apply all the changes shown in the preview
  • Export changes in a file: Save the changes to a dry-run-diff-log.json file without applying them
  • Exit: Cancel the operation without making any changes

Resource Deletion Preview

When AUTH0_ALLOW_DELETE is enabled, dry run will show which resources would be deleted:

# Enable deletions in your config
export AUTH0_ALLOW_DELETE=true
a0deploy import -c config.json -i ./tenant.yaml --dry-run

Resources marked for deletion will appear in the output with DELETE* status, and the asterisk note will explain that AUTH0_ALLOW_DELETE must be enabled for deletions to occur.

Validation and Error Handling

Dry run performs the same validation as a regular deployment:

  • Schema Validation: Ensures all resources conform to Auth0's expected structure
  • Business Rule Validation: Checks for conflicts, required fields, and logical constraints
  • Configuration Validation: Validates keyword replacements and file references

If validation errors are found, dry run will report them without making any changes:

Validation Error: Rule "My Rule" - Names must be unique
Error: Configuration validation failed. No changes made.

No Changes Detected

If no changes are detected between your configuration and the current tenant state, dry run will display:

Auth0 Deploy CLI - Dry Run Preview

Tenant: example-tenant.auth0.com
Input: ./tenant-config/

Simulating deployment... The following changes are proposed:

No changes detected.

Dry Run completed successfully. No changes have been made to your Auth0 tenant.

Best Practices

  1. Always Dry Run First: Make dry run a standard part of your deployment workflow, especially for production environments.

  2. Review All Changes: Carefully examine the proposed changes, paying special attention to deletions and updates to critical resources.

  3. Validate in Stages: For large configuration changes, consider breaking them into smaller deployments and dry running each stage.

  4. Check Dependencies: Ensure that resource dependencies (like client grants referencing specific clients) are properly configured.

  5. Environment Consistency: Use dry run to verify that keyword replacements produce the expected values for your target environment.

Limitations and Considerations

  • State Changes: The actual tenant state may change between running a dry run and the actual deployment. The dry run reflects the state at the time it was executed.

  • API Limitations: Some validation can only be performed during actual API calls. Dry run performs as much validation as possible without making changes.

  • Resource Dependencies: Complex dependencies between resources might only be fully validated during actual deployment.

  • External Factors: Changes made by other users or processes to the Auth0 tenant are not reflected in the dry run results.

Troubleshooting

Common Issues

Configuration Errors: If you see configuration-related errors, verify your keyword replacement mappings and file paths.

Authentication Issues: Ensure your Auth0 client has the necessary scopes to read all resources you're trying to manage.

File Not Found: Check that all referenced files (scripts, templates, etc.) exist and are accessible.

Format Mismatches: Verify that your input format matches your configuration. Using YAML format with JSON-specific dry run configurations may cause issues, and vice versa. Ensure consistency between your input file format and configuration settings.

Getting Help

If you encounter issues with dry run mode:

  1. Enable debug logging: --debug flag or AUTH0_DEBUG=true
  2. Check the troubleshooting guide
  3. Review your configuration against the documentation
  4. Open an issue on the GitHub repository