Ability to export resources manifest required for endpoints deployment

[afprtclr]

Describe the feature.

Users responsible for deploying NServiceBus endpoints to Azure must have specific information readily available to complete deployment tasks, regardless of whether the deployments are manual or fully automated.

The necessary information is most of the time already available in users' code, but it may not be easy to find, interpret, or determine if it is required. Endpoint configuration is not always centralized or is partially dynamic, which further increases difficulty in determining runtime configuration. Core generates a diagnostics file at startup, but this does not contain all information.

NServiceBus endpoints should be capable of outputting all the configuration into a resource manifest.

Examples:

• If the configuration enables the Outbox feature, users must know the name of the Outbox table or of the schema to use with SqlPersistence.
• Users must know the name of the main input queue, the topics to create, and which subscriptions are required.

With this ability users:

• are able to apply Infrastructure as Code (IaC) practices if needed. Examples are Bicep, ARM, CDK, CloudFormation, Terraform, and other solutions;
• are able to compare resource manifests between different endpoint version and different endpoints, without executing installers;
• have governance over infrastructure their endpoints use;
• are able to understand what changes are applied to the shared resources (i.e. databases and message brokers);
• are be able to apply infrastructure changes with company standardized methods of deployments.

This would (partially) resolve the following issue:

• Dedicated connection string for administrative access NServiceBus.RabbitMQ#929
• Challenges with the migration to the topic-per-event topology NServiceBus.Transport.AzureServiceBus#1170

Note

Requires not only an effort within Core, but also in the downstream packages.

The following general information is needed when provisioning endpoints:

• What versions of NServiceBus are used
• What message types are used (including inheritance hierarchy and message assemblies versions)
• What assemblies defining message handlers, sagas, or features are deployed alongside the endpoint. These assemblies may require additional infrastructure
• What Platform components are used (i.e., error instance, audit instance, monitoring instance, etc.)
• Whether the MassTransit Connector is used
• Whether any legacy transport adapter is used

Endpoint details

For each endpoint that needs to be deployed, the following information must be collected to successfully provision infrastructure without using installers:

• Name of the endpoint, which by default determines the main input queue name
• If the endpoint is configured to be uniquely addressable
• Additional queues required by the endpoint (e.g., error, audit, metrics monitoring, heartbeats, and custom checks queues)
• Any custom endpoint satellite queue
• Subscriptions required by the endpoint (e.g., subscription for every event type, manually created subscriptions, etc.)
• Whether the outbox is enabled
• Message types processed by this endpoint alongside their inheritance hierarchy

Transport-specific details

• Topology (e.g., bundle topics, hierarchy bundle, filtering for subscriptions, etc.)
• Infrastructure entity-specific attributes (e.g., queue quotas and delivery count, message TTL, topic names, table name prefixes and schema, etc.)
• Transport-specific entities (e.g., timeout queues, delay queues, dead letter queues, etc.)

Persistence-specific details

• Outbox configuration details (e.g., table schema, names, and prefixes, etc.)
• Saga details (e.g., table schema, names, and prefixes, etc.)
• (Legacy) Timeout details (e.g., prefix and table names for timeout manager, etc.)
• (Legacy) Subscription cache (e.g., prefix and table names, etc.)

Platform-specific details

• Main instance:
• Queues (i.e., input queue, error queue, error forwarding, saga audit queue, audit forwarding queue, queue used for ServiceControl, acknowledgement queue, staging queue for Edit & Retry, throughput data, internal platform errors)
• Database (i.e., the RavenDB instance)
• Audit instance
• Queues (i.e., input queue)
• Metrics instance
• Queues (i.e., input queue)

MassTransit connector details

• The return queue for messages being retried back into production
• Platform-specific queues

Message bridge details

• Queues (e.g., the error queue for the bridge, the endpoint queues that the bridge is connecting, etc.)
• Any subscriptions that need to be bridged

Legacy transport adapter details

• Queues (e.g., audit queue, error queue, control queue, poison message queue, etc.)

Gateway details

• Input queue
• Persistence details
• Incoming ports

Community component details

• Elements required by community components. Details of these elements can be provided by the community component maintainers.

Note

This list is incomplete and needs to be re-evaluated when working on this issue.

With these resource manifests, users are able to run the transport commandline tools with administrative permissions to configure the transport-required infrastructure, and run the endpoints with the least-possible privileges.

Background

An example might be:

myendpoint.exe --export > resource-descriptors.yaml

asb-transport.exe resource-descriptors.yaml

or in code:

EndpointConfiguration endpointConfiguration = ...
var resourceManifest = Installer.GenerateManifest(endpointConfiguration);
using var fs = File.Create("{resourceManifest.Endpoint.Name}.manifest");
resourceManifest.WriteTo(fs);

Related

• Run auto-subscribe as part of installer/setup phase #7338
• Endpoints do not support “desired state” deployment styles (e.g., AWS CDK, Bicep, or Terraform) #7189
• [Spike] Installer support NServiceBus.Extensions.Hosting#304

Additional Context

No response

[jpalac]

We spiked generating a manifest from core, with ASB transport and Sql Persistence.

The PRs were closed due to potentially approaching this from a .NetAspire angle since it already supports infrastructure as code.