Nomadify

Nomadify handles deployments of a .NET Aspire AppHost to HashiCorp Nomad.

Features:

• Raw exec projects
• Docker projects
• Dockerfile projects

Usage:

Run the following command:

dotnet nomadify generate --project-path <path/to/AppHost/project>

and follow the prompts.

Command-line parameters

• project-path: the path to your AppHost project
• aspire-manifest: the path to an existing manifest.json file
• no-build: skips the build
• compression-kind: the compression kind to use. Supported values are: zip, tar
• container-builder: the container builder to use. Supported values are: docker, podman
• runtime-identifier: the runtime identifier to use
• include-dashboard: include the Aspire Dashboard in the deployment (experimental)

What is .NET Aspire?

.NET Aspire is a lightweight, cross-platform, and open-source framework for building microservices and distributed applications. It is designed to be easy to use and provides a set of tools and libraries for building, deploying, and managing microservices. It is built on top of the .NET platform and is compatible with .NET Core and .NET 8+. You can find more information about .NET Aspire on the Aspire website. If you are new to .NET Aspire, I recommend reading the Aspire documentation to get started.

What is Hashicorp Nomad?

HashiCorp Nomad is a flexible, enterprise-grade cluster and application scheduler designed to support the needs of both microservices and traditional applications. It is a single binary that can be used to deploy and manage applications across a cluster of machines. You can find more information about Nomad on the HashiCorp website. If you are new to Nomad, I recommend reading the Nomad documentation to get started.

Service Discovery

Nomadify uses the ServiceDiscovery.Nomad package to find the addresses of services. It works by reading the NOMAD_ADDR_* environment variables at runtime.

How does Nomadify work?

Nomadify reads the Aspire manifest file and generates a Nomad job file for each service. It then builds the service and creates a raw exec archive or a Docker image for it. Finally, it uploads the raw exec project to a file server or the Docker image to a Docker registry and deploys the service to Nomad.

Nomadify will ask you a few questions to get the information it needs to generate the Nomad job file. It will create a nomadify-state.json file, then create a manifest.json file in the folder of your Aspire AppHost project.

The Nomad job file will be created in the same folder as the manifest.json file, or in the output path if specified in the nomadify-state.json file. The job file will be named after the service and will have the extension ".job.hcl". It is generated by using a default values json file which you can specify in the nomadify-state.json file.

Here's an example replacement values file:

{
	"JobDatacenter": "dc1",
	"JobType": "service",
	"JobSemVer": "1.2.3",
	"JobRescheduleDelay": "30s",
	"JobRescheduleDelayFunction": "constant",
	"JobRescheduleUnlimited": true,
	"JobUpdateMaxParallel": "1",
	"JobUpdateMinHealthyTime": "10s",
	"JobUpdateHealthyDeadline": "5m",
	"JobUpdateProgressDeadline": "10m",
	"JobUpdateAutoRevert": true,
	"JobUpdateCanary": "0",
	"JobUpdateStagger": "30s",
	"GroupDesiredInstances": "1",
	"GroupUpdateCanary": "1",
	"GroupUpdateMaxParallel": "5",
    "GroupServiceNameLiteralPrefix": "local/",
    "GroupTaskDriver": "raw_exec",
  	"GroupTaskArtifactDestinationPrefix": "",
	"GroupTaskConfigStartCommand": "/opt/dotnet/dotnet",
	"GroupTaskConfigArgs": ["", ""],
	"GroupTaskServiceProvider": "consul",
	"GroupTaskServiceCheckType": "http",
	"GroupTaskServiceCheckPath": "/health",
	"GroupTaskServiceCheckInterval": "2s",
	"GroupTaskServiceCheckTimeout": "200s"
}

Roadmap

• Dapr support
• Docker compose support
• Aspire Dashboard support

Compatibility

Since Aspire is only supported at its latest version, Nomadify was written for .NET 9.0 and .NET Aspire 9.1, but do try it out with the 8.0 versions of .NET and Aspire and let me know.

Thanks

• Camel icon by Slidicon from The Noun Project
• So much thanks to David Sekula, the author of Aspir8, which gave me a lot of inspiration (and quite a bit of code) and convinced me to do "the same" for Hashicorp Nomad