Skip to content

Defang Pulumi Provider Docs #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Dec 12, 2024
Merged

Defang Pulumi Provider Docs #143

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f1af36f
document pulumi
jordanstephens Dec 8, 2024
da74dc1
Apply suggestions from code review
commit111 Dec 10, 2024
aa31452
move intro sentence above video
commit111 Dec 11, 2024
e998b41
number steps for headings
commit111 Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 94 additions & 7 deletions docs/concepts/pulumi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,11 @@ import TabItem from '@theme/TabItem';
Pulumi support is currently only available for Defang Playground. We are working on support for Defang BYOC.
:::

You can use Pulumi to define your Defang services. This allows you to integrate your Defang services with other cloud resources.
[Pulumi](https://www.pulumi.com) is a modern infrastructure-as-code toolkit that allows developers to use a programming language like Typescript to provision and manage cloud resources.

For example, you might define an Aiven PostgreSQL database in your Pulumi code and then use the outputs of that resource to configure the secrets to connect to the database in your Defang service.
Defang providers a Pulumi [_Provider_](https://www.pulumi.com/docs/iac/concepts/resources/providers/) written in Typescript which can be used to deploy Defang services alongside other pulumi-managed infrastructure.

It also allows you to manage configuration for different environments using Pulumi's config system.

## Defang Pulumi Provider
## Install the Defang Pulumi Provider

To get started with Pulumi and Defang you will need to install the Defang provider in [your Pulumi project](https://www.pulumi.com/learn/pulumi-fundamentals/create-a-pulumi-project/):

Expand Down Expand Up @@ -47,8 +45,15 @@ yarn add @defang-io/pulumi-defang
</TabItem>
</Tabs>

## When to Use the Defang Pulumi Provider

The Defang Pulumi Provider supports developer's with more complex requirements than a [Compose File](/docs/concepts/compose) will support.

One reason to use the Defang Pulumi provider is if wish to integrate your services with other cloud resources. This is particularly true if you need to configure your services dynamically as other cloud resources are being provisioned.

Another reason would be if you want to deploy your services alongside cloud-specific resources, like a DynamoDB table, or an S3 bucket.

## Sample
## Example

The following is a minimal example of a Pulumi program that defines a Defang service:

Expand All @@ -63,4 +68,86 @@ const service = new defang.DefangService("my-service", {
protocol: "http",
}],
});
```
```

:::info
See the [Deploy using Pulumi](/docs/tutorials/deploy-using-pulumi) tutorial for more information about how to use it.
:::

## API

### `DefangService`

```typescript
constructor(
name: string,
args: DefangServiceArgs,
opts?: pulumi.CustomResourceOptions
)
```

### `DefangServiceArgs`

```typescript
interface DefangServiceArgs {
/** the DNS name of the Defang Fabric service; defaults to the value of DEFANG_FABRIC or prod, if unset */
fabricDNS?: pulumi.Input<string>;
/** the name of the service; defaults to the name of the resource */
name?: pulumi.Input<string>;
/** the container image to deploy; required when no build configuration was provided */
image?: pulumi.Input<string>;
/** the platform to deploy to; defaults to "linux/amd64" */
platform?: pulumi.Input<Platform>;
/** which network the service is in, ie. whether the service requires a public IP or not; defaults to "private" (was: internal=true) */
networks?: { [key in NetworkName]?: Network };
/** the optional deployment configuration */
deploy?: pulumi.Input<Deploy>;
/** the ports to expose */
ports?: pulumi.Input<pulumi.Input<Port>[]>;
/** the environment variables to set; use `null` to mark at sensitive */
environment?: pulumi.Input<{ [key: string]: pulumi.Input<string> | null }>;
/** the secrets to expose as environment variables @deprecated use environment key with value `null` */
secrets?: pulumi.Input<pulumi.Input<Secret>[]>;
/** force deployment of the service even if nothing has changed */
forceNewDeployment?: pulumi.Input<boolean>;
/** the command to run; overrides the container image's CMD */
command?: pulumi.Input<pulumi.Input<string>[]>;
/** the optional build configuration; required when no image was provided */
build?: pulumi.Input<Build>;
/** the optional health-check test for the service */
healthcheck?: pulumi.Input<HealthCheck>;
/** the optional fully qualified domain name for the service; requires CNAME to the publicFqdn */
domainname?: pulumi.Input<string>;
/** experimental: mark this service as (managed) Redis */
x_redis?: pulumi.Input<unknown>;
/** experimental: mark this service as serving static files */
x_static_files?: pulumi.Input<StaticFiles>;
/** if true, this provider will wait for the service to reach a steady state before continuing */
waitForSteadyState?: pulumi.Input<boolean>;
/** the project to deploy the service to */
project?: pulumi.Input<string>;
}
```

### `Platform`

```typescript
type Platform = "linux/arm64" | "linux/amd64" | "linux";
```

### `Protocol`
```typescript
type Protocol = "tcp" | "udp" | "http" | "http2" | "grpc";
```
### `DeviceCapability`
```typescript
type DeviceCapability = "gpu";
```
### `NetworkName`
```typescript
type NetworkName = "private" | "public";
```
### `Network`
```typescript
type Network = { aliases?: string[] } | null;
```
52 changes: 26 additions & 26 deletions docs/tutorials/deploy-using-pulumi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,33 +5,41 @@ sidebar_position: 400

# Deploy Using Pulumi

:::warning
At the time of writing, the Defang Pulumi Provider only works with [Defang Playground](../concepts/defang-playground.md). We are working on [BYOC](../concepts/defang-byoc.md) support.
:::

<iframe width="560" height="315" src="https://www.youtube.com/embed/A4uiP5FIgg0?si=BHZLOxN4noJ56f7x" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Installing Dependencies
This tutorial will show you how to deploy minio with Pulumi using the Defang Provider.

Make sure to install the [Pulumi CLI](https://www.pulumi.com/docs/install/) and the [Defang CLI](../getting-started#install-the-defang-cli.md).
## Pre-requisites

Make sure you are logged into the [Defang CLI](/docs/concepts/authentication.md). Don't worry about the Pulumi CLI for now.
* [A Defang Account](/docs/concepts/authentication)
* [Pulumi CLI](https://www.pulumi.com/docs/install)
* [The Defang CLI](/docs/getting-started#install-the-defang-cli)
* [The Defang Pulumi Provider](/docs/concepts/pulumi#install-the-defang-pulumi-provider)

## Project Directory Setup
## Authenticate With Defang

Create a new directory for your project and navigate to it.
Make sure you are logged into [Defang CLI](/docs/concepts/authentication.md). Don't worry about the Pulumi CLI for now.

## Configure the Pulumi Backend

Navigate to your project directly. (If you don't have a project yet, try one of our [samples](https://defang.io/#samples))

```bash
mkdir project && cd project
```

If you're familiar with Pulumi and/or are already logged in with the Pulumi CLI, you can skip the next step.
Pulumi uses the `pulumi login` command to select a backend. In this tutorial, we will use the Local Filesystem backend for simplicity. When you are ready to deploy to production, you will probably want to look into other [Pulumi backend options](https://www.pulumi.com/docs/iac/concepts/state-and-backends).

If you are new to Pulumi and/or don't have an account, you can "login" to the filesystem by running the following command:
Run the following command to "login" to the filesystem backend in the local directory.

```bash
pulumi login file://./
```

This will make the Pulumi CLI store the state of your infrastructure in the current directory.

## Initialize the Project
## Initialize the Pulumi Project

Run the following command to set your encryption passphrase for this terminal session:

Expand All @@ -53,17 +61,9 @@ Run the following command to add to the `.gitignore` file:
echo ".pulumi" >> .gitignore
```

## Install the Defang Provider
## Write Your Pulumi Code

Run the following command to install the Defang provider:

```bash
npm install @defang-io/pulumi-defang
```

## Write the Pulumi Code

Your `index.ts` file should look like this:
Create an `index.ts` file to contain your Pulumi code. This code will describe our services, our service's dependencies, and our service's configuration.

```typescript
import * as defang from '@defang-io/pulumi-defang/lib';
Expand Down Expand Up @@ -109,11 +109,7 @@ export const service = new defang.DefangService('minio', {

## Deploy to Defang

:::warning
At the time of writing, the Defang Pulumi Provider only works with [Defang Playground](../concepts/defang-playground.md). We are working on [BYOC](../concepts/defang-byoc.md) support.
:::

Run the following command to deploy your service:
Now we're ready to deploy to Defang with Pulumi! Run the following command to deploy your service:

```bash
pulumi up --stack=dev
Expand Down Expand Up @@ -144,3 +140,7 @@ To clean up the deployment, run the following command:
```bash
pulumi destroy --stack=dev
```

## More Info

See the [Pulumi concept docs](/docs/concepts/pulumi) for more information about the Defang Pulumi Provider.
Loading