Merge pull request #143 from DefangLabs/jordan/pulumi-docs

jordanstephens · web-flow · commit 1884950b4be0 · 2024-12-12T15:01:51.000-08:00
Defang Pulumi Provider Docs
diff --git a/docs/concepts/pulumi.md b/docs/concepts/pulumi.md
@@ -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 provides 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/):
 
@@ -47,8 +45,15 @@ yarn add @defang-io/pulumi-defang
   </TabItem>
 </Tabs>
 
+## When to Use the Defang Pulumi Provider
+
+The Defang Pulumi Provider is a good option for developers with more complex requirements than those supported by a [Compose File](/docs/concepts/compose).
+
+One reason to use the Defang Pulumi provider is if you 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:
 
@@ -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;
+```
diff --git a/docs/tutorials/deploy-using-pulumi.mdx b/docs/tutorials/deploy-using-pulumi.mdx
@@ -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.
+:::
+
+This tutorial will show you how to deploy Minio with Pulumi using the Defang Provider.
+
 <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
+## Pre-requisites
 
-Make sure to install the [Pulumi CLI](https://www.pulumi.com/docs/install/) and the [Defang CLI](../getting-started#install-the-defang-cli.md).
+* [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)
+
+## Step 1 - Authenticate With Defang
 
 Make sure you are logged into the [Defang CLI](/docs/concepts/authentication.md). Don't worry about the Pulumi CLI for now.
 
-## Project Directory Setup
+## Step 2 - Configure the Pulumi Backend
 
-Create a new directory for your project and navigate to it.
+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
+## Step 3 - Initialize the Pulumi Project
 
 Run the following command to set your encryption passphrase for this terminal session:
 
@@ -53,17 +61,9 @@ Run the following command to add to the `.gitignore` file:
 echo ".pulumi" >> .gitignore
 ```
 
-## Install the Defang Provider
-
-Run the following command to install the Defang provider:
-
-```bash
-npm install @defang-io/pulumi-defang
-```
-
-## Write the Pulumi Code
+## Step 4 - Write Your 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';
@@ -107,27 +107,23 @@ 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.
-:::
+## Step 5 - Deploy to Defang
 
-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
 ```
 
-## Monitor the Deployment
+## Step 6 - Monitor the Deployment
 
 You can monitor the deployment by running the following command:
 
 ```bash
 defang tail --name minio
 ```
 
-## Logging Into Minio
+### Logging Into Minio
 
 The [Defang Playground](../concepts/defang-playground.md) will give you a domain, which you can obtain by running the following command:
 
@@ -137,10 +133,14 @@ defang ls | grep 'minio.*9001'
 
 If you navigate to the domain in your browser, you will be prompted to log in. Use the username `minio` and the password `minio123`.
 
-## Clean Up
+### Clean Up
 
 To clean up the deployment, run the following command:
 
 ```bash
 pulumi destroy --stack=dev
 ```
+
+---
+
+See the [Pulumi concept docs](/docs/concepts/pulumi) for more information about the Defang Pulumi Provider.
