You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on May 20, 2025. It is now read-only.
Copy file name to clipboardExpand all lines: docs/basics/deployment.mdx
+88-48Lines changed: 88 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,76 +4,116 @@ description: 'How to deploy Nitric applications'
4
4
5
5
# Deployment
6
6
7
-
Nitric can automatically deploy your application to a supported cloud provider. As discussed in the [concepts](/concepts/how-nitric-works) page, Nitric has three standard `providers`, one each for [AWS](/reference/providers/aws), [Google Cloud](/reference/providers/gcp)and [Azure](/reference/providers/azure). If none of those fit your needs you're also able to [build a custom provider](/reference/providers/custom/building-custom-provider) to target the host you prefer with your own tools and configuration.
7
+
Nitric applications are decoupled from the underlying hosting provider, allowing you to develop your application locally and deploy it to your preferred cloud provider or another platform without these concerns bleeding into the application code.
8
8
9
-
The Nitric CLI command to perform deployments is `nitric up`. However, before your first deployment you'll need to create a `stack`, stacks represent deployment targets. If you haven't created a stack before we recommend reading the steps in our [quickstart guide](/getting-started/quickstart#deploying-the-app). The `up` command will prompt you to create a <ahref="/docs/concepts/project-structure#stack-files"target="_blank">stack</a> if you haven't already created one for you project.
9
+
You can read more the [concepts](/concepts/how-nitric-works) behind Nitric to understand why this separation is important and how it is achieved. This page will focus on the deployment process and how to configure your application for deployment.
10
10
11
-
```bash
12
-
nitric up
13
-
```
11
+
<Note>
12
+
If you're new to Nitric we recommend starting with the [quickstart
13
+
guide](/guides/quickstart) to get a feel for how Nitric works. You can return
14
+
to this page later to learn more about the deployment process and how to
15
+
customize it.
16
+
</Note>
14
17
15
-
To tear down a previously deployed application use the `down` command.
18
+
## Provider Types
16
19
17
-
```bash
18
-
nitric down
19
-
```
20
+
The plugins used to deploy your application to a specific target platform are called [providers](/reference/providers). Typically providers do one of two things:
21
+
22
+
1.**Deploy your application directly**
23
+
2.**Generate Infrastructure-as-Code**
20
24
21
-
## Providers
25
+
The first option is useful for simplicity, where you deployment automation is handled directly by the provider plugin. The second option is useful for more complex deployments where you want to manage the infrastructure as code yourself.
22
26
23
-
Each of your project's stacks will target a specific hosting platform. The plugins that perform the deployments to these platforms are called `providers`. Nitric currently has 3 official providers, one each for [AWS](/reference/providers/aws), [Google Cloud](/reference/providers/gcp) and [Azure](/reference/providers/azure). All of the official providers use [Pulumi](https://pulumi.com) under the hood for their deployments, so Pulumi will need to be configured to persist your stack state and to run the deployment to the cloud of your choice.
27
+
For example, if you prefer to use Terraform and you rely on other Terraform tools for policy enforcement, or cost estimation, you can use or build a provider that generates Terraform code for you to deploy. This allows you to use Nitric's deployment automation and still leverage your existing Terraform workflows.
24
28
25
-
### Configuring cloud credentials
29
+
Alternatively, if you're looking for a simple deployment process, you can use or build a provider that deploys your application directly to your cloud provider of choice.
26
30
27
-
You will need to configure your cloud credentials, either locally or in your CI/CD pipeline, to allow Nitric to create resources in a cloud account. Instructions on how to setup credentials for your target provider can be found in the provider documentation: [AWS](/reference/providers/aws), [Google Cloud](/reference/providers/gcp) and [Azure](/reference/providers/azure).
31
+
It's important to know which type of provider you're using, as the configuration options and deployment process will differ between them.
28
32
29
-
### Configuring state backend
33
+
Nitric ships with five official providers. The first three are direct deployment providers, and the last two are IaC providers.
30
34
31
-
To track the state of your stack between deployments you'll need to configure a location for Pulumi to store its stack state (also known as a 'backend'). Pulumi provides several options for state backends, a common choice is [Pulumi's managed service](https://www.pulumi.com/docs/concepts/state/#pulumi-cloud-backend) which stores state in the cloud allowing for secure storage and collaboration. Alternatively, you can use any other state [backends](https://www.pulumi.com/docs/concepts/state/#using-a-self-managed-backend) Pulumi support.
35
+
### Direct Deployment Providers
36
+
37
+
All of the direct deployment providers use [Pulumi](https://pulumi.com) under the hood for their deployments, so Pulumi will need to be configured to persist your stack state and to run the deployment to the cloud of your choice.
38
+
39
+
-[AWS](/reference/providers/aws)
40
+
-[Google Cloud](/reference/providers/gcp)
41
+
-[Azure](/reference/providers/azure)
32
42
33
43
<Note>
34
-
If you're trying Nitric for the first time we recommend starting with a
35
-
`local` backend, which stores the stack state in a file on your machine. If
36
-
you haven't already configured a backend for Pulumi, Nitric will prompt you to
37
-
automatically setup this local backend when you run `nitric up`.
44
+
If you're new to Nitric we recommend starting with one of the direct
45
+
deployment providers for simplicity.
38
46
</Note>
39
47
40
-
##Configuring stacks
48
+
### Infrastructure-as-Code Providers
41
49
42
-
When using stacks to deploy to different environments such as a development, testing or production environment, you'll typically want to go beyond the default configuration Nitric uses when deploying cloud resources. This environment specific configuration is added to the stack files.
50
+
All of the IaC providers generate Terraform code for deployment. This allows youto use Nitric's deployment automation and still leverage your existing Terraform workflows.
43
51
44
-
When deploying the application, you can add extra configuration for specific services or globally for all services. This configuration is unique to each stack file, allowing you to deploy the same application to different environments with different configurations. Since the configuration options available are unique to the cloud platform and the services they offer these settings are typically different between provider implementations.
52
+
-[AWSTF](/reference/providers/awstf)
53
+
-[GCPTF](/reference/providers/gcptf)
45
54
46
-
Below is an example of configuration added to an AWS stack to augment the memory, timeout, and telemetry sampling percentage for deployed services.
55
+
<Note>An Azure Terraform provider is in development.</Note>
These providers are also a good starting point for customization when you have existing Terraform Modules or workflows you want to integrate with Nitric.
58
+
59
+
## Custom Providers
60
+
61
+
If you have a specific cloud service, deployment workflow or tooling you want to use, you can build a [custom provider](/reference/providers/custom). Custom providers allow you to target the host you prefer with your own tools and configuration.
62
+
63
+
You can also extend the existing providers to change which cloud services are used to fulfill the Nitric resource contracts, to add configuration options or to change the deployment process.
64
+
65
+
## Deploying your application
66
+
67
+
Read the concepts page on [deployment](/concepts/deployment) to understand how Nitric prepares your application for deployment. This section focuses on how to configure your application for deployment and how to deploy it.
68
+
69
+
There are two primary commands for deploying your application with Nitric:
70
+
71
+
-`nitric up` - Build the application and run the provider plugin to deploy it
72
+
-`nitric down` - Run the provider plugin to tear down the application
60
73
61
-
Note that the configuration above creates two types of services with different configuration for each. The `default` configuration, which we'll apply to most services. There is also a `memory-optimized` handler group, which we've used to allocate more memory to those services specifically.
74
+
<Note>
75
+
The `nitric down` is only available for [direct deployment
76
+
providers](#direct-deployment-providers). If you're using an IaC provider
77
+
you'll need to manage deployments and teardowns with your IaC tooling, such as
78
+
Terraform.
79
+
</Note>
80
+
81
+
These commands are used to deploy [stacks](#stacks) to different environments, such as development, testing, or production.
82
+
83
+
### `nitric up`
84
+
85
+
The Nitric CLI command to perform builds/deployments is `nitric up`. This command performs the following steps:
86
+
87
+
1.**Build the application**: Nitric will build the application using the configuration in the `nitric.yaml` file. This includes building container images for each service.
88
+
2.**Run the application in resource collection mode**: Nitric will run the application in a mode where it collects the resources used by the application. This is used to generate the graph of cloud resources required to run the application.
89
+
3.**Run the provider plugin**: Nitric will run the provider plugin to deploy the application to the target platform. The provider plugin will use the resource graph and service container images to create the required cloud resources.
90
+
91
+
In the case of direct deployment providers, the provider plugin will use the embedded IaC tool of choice to deploy the application. For the official providers, this is Pulumi.
92
+
93
+
In the case of IaC providers, the provider plugin will generate IaC code for you using existing tools, such as the Terraform CLI. This code is typically output to a directory in your project, which you can then use to deploy the application with your existing CI/CD workflows. For example, you might commit the generated IaC code to a repository and use a CI/CD pipeline to deploy the application.
94
+
95
+
### `nitric down`
62
96
63
-
To apply these handler group configurations, we need to create the groups. That's done by updating the project file to create groups and match them to different source code locations:
97
+
The Nitric CLI command to tear down the application is `nitric down`. This command simply runs the provider plugin to tear down the application. This command is only available for direct deployment providers.
64
98
65
-
```yaml {{ tag: "nitric.yaml"}}
66
-
name: my-project
67
-
services:
68
-
- match: services/*.ts
69
-
start: ts-node $SERVICE_PATH
70
-
type: default
71
-
- match: custom/*.ts
72
-
start: ts-node $SERVICE_PATH
73
-
type: memory-optimized
99
+
## Stacks
100
+
101
+
Since an application can be deployed to multiple environments and cloud providers, Nitric uses stack files to identify these deployment targets. These files can be created by running the `nitric stack new` CLI command.
102
+
103
+
Stack files define the deployment plugin (provider), any additional configuration required by that plugin for it to be able to generate IaC or deploy your application. Most configuration options available in the stack files are specific to the provider you're using.
104
+
105
+
The common configuration option available in all stack files is the `provider` field, which specifies the provider plugin to use for the deployment. The standard format for specifying a provider is `[namespace]/[provider]@[version]`. The `namespace` for all standard providers is `nitric`. The `provider` is the name of the provider plugin, and the `version` is the version of the provider plugin to use.
106
+
107
+
There is another format for specifying providers as a container image `docker://[image]`, which you can read about in the [reference docs](/reference/providers/custom/docker).
108
+
109
+
Here is a basic example, using the standard nitric AWS provider `nitric/[email protected]`.
Provider specific stack configuration can be viewed in the reference docs for each [provider](/reference/providers).
116
+
Provider specific stack configuration, including advanced configuration options, can be viewed in the reference docs for each [provider](/reference/providers).
Copy file name to clipboardExpand all lines: docs/concepts/security.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
---
2
-
description: 'How Nitric deals with IAM and access control'
2
+
description: 'How Nitric deals with security, IAM and access control'
3
3
---
4
4
5
-
# Access Control
5
+
# Security
6
6
7
7
Cloud Identity and Access Management (IAM) can be challenging. Understanding, creating and applying policies with the right combination of Principals, Actions and Resources that allow 'just enough' access to desired resources without unintentional errors is time consuming.
description: 'Build or extend a custom provider for Nitric'
3
+
---
4
+
5
+
# Custom Providers
6
+
7
+
Custom providers allow you to target the services and host(s) you prefer with your own tools and configuration. You can also extend the existing providers to change which cloud services are used to fulfill the Nitric resource contracts, to add configuration options or to change the deployment process.
8
+
9
+
The standard providers that ship with Nitric are great to get started and move quickly, but the intention of Nitric is to unlock portability and separate the deployment process from the application code. This is where custom providers come in.
10
+
11
+
There are two main ways to create a custom provider:
12
+
13
+
1.**Create a new provider**: This is the most flexible option, but also the most complex. You can [create a new provider from scratch](./custom/create)
14
+
2.**Extend an existing provider**: This is a good option if you want to leverage the existing provider's deployment automation and only need to make specific changes, such as use your own Terraform modules or deploy Nitric resources to a different cloud service. You can [extend an existing provider](./custom/extend) to add your own configuration options or change the deployment process.
You will need to configure your cloud credentials, either locally or in your CI/CD pipeline, to allow Nitric to create resources in a cloud account. Instructions on how to setup credentials for your target provider can be found in the provider documentation: [AWS](/reference/providers/aws), [Google Cloud](/reference/providers/gcp) and [Azure](/reference/providers/azure).
4
+
5
+
### Configuring state backend
6
+
7
+
To track the state of your stack between deployments you'll need to configure a location for Pulumi to store its stack state (also known as a 'backend'). Pulumi provides several options for state backends, a common choice is [Pulumi's managed service](https://www.pulumi.com/docs/concepts/state/#pulumi-cloud-backend) which stores state in the cloud allowing for secure storage and collaboration. Alternatively, you can use any other state [backends](https://www.pulumi.com/docs/concepts/state/#using-a-self-managed-backend) Pulumi support.
8
+
9
+
<Note>
10
+
If you're trying Nitric for the first time we recommend starting with a
11
+
`local` backend, which stores the stack state in a file on your machine. If
12
+
you haven't already configured a backend for Pulumi, Nitric will prompt you to
13
+
automatically setup this local backend when you run `nitric up`.
0 commit comments