Proposal: Resource Exclusion

[willvedd]

• Start Date: March 14, 2022
• Github Issue: Proposal: Resource Exclusion · Issue #451

Summary

We propose a mechanism for excluding entire resources from the management purview of Deploy CLI.

Resource exclusion is an often requested feature from the community and has many legitimate use-cases. Currently, there is some resource-specific exclusion functionality, on a per-ID basis, but nothing that excludes entire resource types.

Why Exclude?

Excluding entire resources are useful for developers who work on tenants with many of a certain type. In the case of hundreds or thousands of a type of resource, it may be operationally inconvenient to manage all of those configurations.

Additionally, exclusion is useful for organizations who provision certain resource types manually or through different API means, and they do not wish to automate that resource type under the purview of deploy CLI.

It is understood that exclusions operate bi-directionally, meaning they work both on import and export. Currently, there is no clear use case for excluding resources for only one direction.

Existing Methods of Exclusion #

The following are existing configuration values for excluding resources on a per-ID basis:

• AUTH0_EXCLUDED_RULES
• AUTH0_EXCLUDED_CLIENTS
• AUTH0_EXCLUDED_DATABASES
• AUTH0_EXCLUDED_CONNECTIONS
• AUTH0_EXCLUDED_RESOURCE_SERVERS

There are key issues these configurations though:

1. They only apply on a per-ID basis, meaning that there is no way to automatically exclude all of that certain resource. This is a minor inconvenience for a handful of a certain resource, however, in the case of hundreds or thousands of a certain resource, it becomes untenable. Further, as more of a certain resource gets added, they'll necessarily need to be added to the Deploy CLI configuration, requiring more touch points.

2. This only covers a subset of all resources. The Auth0 Management API is still expanding in scope, and exclusions for each resource Granted, it is possible to accommodate all n number of resource types with n number of exclusion properties, but can become unmanageable

3. Many entities may rely upon another specific resource in a complex web of dependencies. Each specific dependency is difficult to manage within the tool. For the simplicity and reliability of operation, it would be better to remove per-ID exclusions in favor of broader exclusions that can be more predictably managed.

Deprecation

The intention is to eventually deprecate the smaller, bespoke, exclusion configurations.

The reasoning is, that the Deploy CLI is positioned as a bulk configuration management tool. While configurable to omit certain resources, it is best suited for migrating large sets of tenant configuration. For more bespoke and granular control over the purview of configuration management, the Auth0 Terraform Provider may be a more appropriate tool for your workflow.

Further, omitting specific IDs from the management of this tool can have unintended and seemingly unpredictable consequences. Especially in the case of an entity depending on the existence of another.

Deprecation will not be immediate and will begin initially by displaying warning notifications in the console. Developers will be encouraged to adopt the broader method of exclusion proposed in this document.

Proposed Solution

The proposed solution is to introduce an AUTH0_EXCLUDED property in the user-defined JSON configuration file. This property will be an array of strings which contain the names of the resources that are intended for exclusion, providing the flexibility to target any and all resources.

An example of a user-defined JSON configuration file:

{
    "AUTH0_DOMAIN": "<DOMAIN>",
    "AUTH0_CLIENT_ID": "<CLIENT_ID>",
    "AUTH0_CLIENT_SECRET": "<CLIENT_SECRET",
    "AUTH0_ALLOW_DELETE": false,
    "AUTH0_EXCLUDED": [
        "connections",
        "rules",
        "actions",
    ]
}

Future Extensibility

Worth noting is that the proposed AUTH0_EXCLUDED property does yield a clear path for excluding specific IDs within a certain resource type in the future. This decision is intentional and meant to more clearly position this application as a bulk configuration management tool.

In the future however, it may be possible for this tool to include a AUTH0_INCLUDED property in combination with a wildcard operator available for AUTH0_EXCLUDED. Example:

{
    "AUTH0_EXCLUDED": "*",
    "AUTH0_INCLUDED": [
        "connections",
        "rules",
        "actions",
    ]
}

This would open the possibility to flip application to an opt-in paradigm as opposed to the current opt-out behavior.

Relevant Github Issues

• Provide a way to exclude all of an object during a0deploy import · Issue #375

• Add config to exclude Actions - AUTH0_EXCLUDED_ACTIONS · Issue #397

• Ability to exclude objects when import/export using deploy-cli · Issue #394

• Allow skipping export of Organizations · Issue #427

[stuarthadfieldglobality]

Hey @willvedd.

Gonna chime in here. I think you've captured the essence of the problem really well, and I'm on board with the proposed solution.

The only things I'd call out are:

1. AUTH0_EXCLUDED is fairly nondescript, and as all engineers know, source code and functionality therein and documentation have an uncanny habit of getting misaligned. I'd love to see documentation being added as an AC for this.
2. I'm sure it's implied, but worth calling out in the proposal - resources in the EXCLUDED list are excluded bidirectionally, correct? As in, they will neither be imported nor exported.

I don't want to get too caught up in the future work section, I have some thoughts but let's cross that bridge when we get to it!

[MGough]

Sorry for the delay in getting to review this proposal. I appreciate that Auth0 have started to assign time for the development of these libraries, and make it a viable product.

The reasoning is, that the Deploy CLI is positioned as a bulk configuration management tool. While configurable to omit certain resources, it is best suited for migrating large sets of tenant configuration. For more bespoke and granular control over the purview of configuration management, the Auth0 Terraform Provider may be a more appropriate tool for your workflow.

This is news to me! Previously the Deploy CLI seemed to be positioned as a general CI/CD tool. When I started using it nearly a year and a half ago there wasn't much of an alternative that I could find. The terraform provider may have existed but when I have seen it in the past it wasn't tracking with feature development, and it wasn't managed by the Auth0 team. So you may find others who are surprised by this.

As a slight aside... One of the strengths of this tool compared to the terraform alternative was being able to allow a development tenant to be managed via the dashboard, then exporting the config, storing the alterations in source control, and knowing that it would work when applied to another environment/tenant. With terraform it's trickier as you need to work out which resources that you need before you can import them. You can see how I managed it for our team using yarn scripts in my demo repo: https://github.com/MGough/auth0-trunk-based-deployments

As far as the proposal goes, it looks reasonable and hopefullly addresses the issues others face. It most likely signals the start of the end of my time using this tool. It makes sense not to have two different tools for the same purpose, I'll have to see about getting us migrated across to terraform for Auth0.

[willvedd]

@stuarthadfieldglobality

AUTH0_EXCLUDED is fairly nondescript, and as all engineers know, source code and functionality therein and documentation have an uncanny habit of getting misaligned. I'd love to see documentation being added as an AC for this.

I agree with both points here. Documentation is indeed part of the acceptance criteria and understood to be a sore spot with this project. Expect updates to our documentation in the near future.

I'm sure it's implied, but worth calling out in the proposal - resources in the EXCLUDED list are excluded bidirectionally, correct? As in, they will neither be imported nor exported.

Correct. This will eliminate API calls in both directions and effectively ignore a targeted resource type from purview.

[willvedd]

@MGough Thank you for the helpful feedback. I'm especially interested in https://github.com/MGough/auth0-trunk-based-deployments, it's a hidden gem that reveals quite a bit about the usage of the Deploy CLI. I'll make sure to have it reviewed with the engineering and product team. We may ask you some follow-up feedback in the future!

[willvedd]

Update: As a feature this has been implemented and released in v7.7.0. Please see #468 for more information about the implementation itself.

Example usage:

{
  "AUTH0_DOMAIN": "test.us.auth0.com",
  "AUTH0_CLIENT_ID": "FOO",
  "AUTH0_CLIENT_SECRET": "foobarsecret",
  "AUTH0_EXCLUDED": [
    "pages",
    "organizations",
    "clients"
   ]
}

The only outstanding piece for this proposal is the documentation, which will likely come in the form of a complete documentation overhaul in Q2.

[mendhak]

I'd like to echo @MGough comments above (regarding the surprise!)

The reasoning is, that the Deploy CLI is positioned as a bulk configuration management tool.

This isn't how it was positioned when we started using it, we were specifically told by Auth0 TAMs that this was the best way to manage resources both individually and in bulk, so I don't see where the 'bulk only' reasoning has come from.

Further, switching to another method (the Terraform one), just for the sake of a few exclusions, is a non trivial task. This tool comes with its own workflows, environmental substitutions, configuration, multi-tenant deployments, The Terraform provider has its own workflow and also introduces the overhead of state management.

IMO this new positioning has not been communicated (or communicated well). Could the existing exclusion types be kept for the sake of backward compatibility?

[aeimer]

As we only want to deploy specific parts (like hooks, actions and in a second repo only the html templates) this setting would make our setup more resilient against new properties/changes.

[charliearaya]

Will I still be able to exclude one specific client?

[willvedd]

Will I still be able to exclude one specific client?

@charliearaya For the time-being, yes. However we are considering removing by-ID exclusions for future major releases. The idea being that the Deploy CLI may be better suited for bulk management with less granular precision over configuration management than something more suited for that type of management strategy, namely the Auth0 Terraform Provider. Excluding by ID for some resource types sets a unsustainable precedent for others, it wouldn't be feasible to implement across the rest of the codebase and it exposes us to non-trivial edge cases. I can see us maintaining some per-ID exclusion configurations given that there's enough of a use-case. So with that said, do you mind sharing why you'd want to exclude a specific client by ID?

As an aside, more work still needs to be done on how we position this tool vs the Terraform provider. Nothing is set in stone yet, we're still trying to get a sense of where the edges are/should be. Part of that is soliciting feedback.

[potatopeelings]

So with that said, do you mind sharing why you'd want to exclude a specific client by ID?

I have a tenant where I've added a rule specifically for Testing. I'd like to exclude this rule from the main Auth0 repository (since I wouldn't want this to go to the production tenant).

I think the similar use cases would apply for Clients created specifically for testing.

[charliearaya]

Will I still be able to exclude one specific client?

So with that said, do you mind sharing why you'd want to exclude a specific client by ID?

In my case I have to manually create a M2M application whose credentials I use for auth0-deploy-cli, there is no need to have this application inside my template because it will be created beforehand. Although it wont hurt to include it in the template it feels unnecessary

[mendhak]

So with that said, do you mind sharing why you'd want to exclude a specific client by ID?

Same as above, we usually exclude the Auth0 Deploy CLI's own M2M. Also the Auth0 Management API resource-server. Some of the extensions that have to be created by hand, such as the Delegated Admin Extension, create their own configuration/client configuration. That too gets excluded.

And sometimes we'll have long running test/experimental configurations that we want to exclude, eg a new connection type, a new rule (hopefully a new action).

[mayc2]

So with that said, do you mind sharing why you'd want to exclude a specific client by ID?

I also have similar use cases due to the fact that we manage tenants for dev, staging, prod, as well as for internal vs external facing applications.

We use extensions (and thus client/apis), social connections, and rules in dev or internal tenants that we would like to exclude when porting config to staging or prod.
By not allowing specific excludes, this makes this process much less automated. Further, it makes the diff much more difficult to read as well (in addition to this #328) that adds noise as well.

[willvedd]

Really happy with the feedback we received on this one. Can assure everyone that we've ingested and internalized all comments. I'm going to close this one out though because the conversation has dwindled and the exclusion functionality has been live for several months now. But I look forward to soliciting feedback from you folks in the future!

[jigar-kachhia-vts]

Ideally, we want specific resource to be exclude and this feature to AUTH0_EXCLUDED_CLIENTS import when we have multiple resource and we just want to exclude specific or include specific. This mainly help during local setup.