Merge branch 'main' into removing-question-mark-schedule

winglang · Mar 11, 2024 · 1355d34 · 1355d34
2 parents 803fef9 + dc29f19
commit 1355d34
Show file tree

Hide file tree

Showing 35 changed files with 485 additions and 316 deletions.
diff --git a/docs/docs/02-concepts/03-platforms.md b/docs/docs/02-concepts/03-platforms.md
@@ -7,8 +7,6 @@ keywords: [platforms, targets, target, platform, aws, gcp, azure, sim, terraform
 
 When working with the Wing programming language, an integral part of the compilation process is the use of platform. In essence, platform specify how and where your application is deployed. They determine both the cloud environment and the provisioning engine that the code will be deployed with.
 
-## Platforms
-
 You can view the list of available builtin platform with the `wing compile --help` command. Here is an example of the output:
 
 ```sh
@@ -83,11 +81,17 @@ Though this may be a bit verbose. As an alternative you can use a values file. V
 Here is an example of using a `wing.toml` file to provide the same parameters as above:
 
 ```toml
-[tf-aws]
-vpc = "existing"
-vpcId = "vpc-1234567890"
-privateSubnetId = "subnet-1234567890"
-publicSubnetId = "subnet-1234567890"
+[ tf-aws ]
+# vpc can be set to "new" or "existing"
+vpc = "new"
+# vpc_lambda will ensure that lambda functions are created within the vpc on the private subnet
+vpc_lambda = true
+# vpc_api_gateway will ensure that the api gateway is created within the vpc on the private subnet
+vpc_api_gateway = true
+# The following parameters will be required if using "existing" vpc
+# vpc_id = "vpc-123xyz"
+# private_subnet_ids = ["subnet-123xyz"]
+# public_subnet_ids = ["subnet-123xyz"]
 ```
 
 #### Target-specific code

diff --git a/docs/docs/055-platforms/_category_.yml b/docs/docs/055-platforms/_category_.yml
@@ -0,0 +1,6 @@
+label: Platforms
+collapsible: true
+collapsed: true
+link:
+  type: generated-index
+  title: Platforms
diff --git a/docs/docs/055-platforms/awscdk.md b/docs/docs/055-platforms/awscdk.md
@@ -0,0 +1,78 @@
+---
+title: AWS CDK
+id: awscdk
+sidebar_label: awscdk
+description: AWS CDK platform
+keywords: [Wing reference, Wing language, language, Wing language spec, Wing programming language, aws, awscdk, amazon web services, cloudformation]
+---
+
+The `@winglang/platform-awscdk` [platform](../02-concepts/03-platforms.md) compiles your program for the AWS CDK (CloudFormation).
+
+## Usage
+
+You will need to install the `@winglang/platform-awscdk` library in order to use this platform.
+
+```sh
+$ npm i @winglang/platform-awscdk
+```
+
+This platform requires the environment variable `CDK_STACK_NAME` to be set to the name of the CDK
+stack to synthesize.
+
+```sh
+$ export CDK_STACK_NAME="my-project"
+$ wing compile --platform @winglang/platform-awscdk [entrypoint]
+```
+
+## Parameters
+
+The `CDK_STACK_NAME` environment variable specifies the name of the CDK stack to synthesize.
+
+## Output
+
+The output includes both a AWS-CDK configuration file (under `target/<entrypoint>.awscdk`) and
+JavaScript bundles that include inflight code that executes on compute platforms such as AWS Lambda.
+
+## Deployment
+
+To deploy your app, you will first need to install the [AWS CDK
+CLI](https://docs.aws.amazon.com/cdk/v2/guide/cli.html).
+
+If not previously done, you will need to bootstrap your environment (account/region):
+
+```sh
+$ cd bootstrap --app target/app.awscdk
+```
+
+And then you can deploy:
+
+```sh
+$ cdk deploy --app target/app.awscdk
+```
+
+## Customizations
+
+### Custom CDK Stack
+
+The `App` class has a `stackFactory` property that can be used to customize how the root CDK stack
+is created.
+
+To use this, create a custom platform like this:
+
+```js
+import { App } from "@winglang/platform-awscdk";
+import { platform } from "@winglang/sdk";
+
+export class Platform implements platform.IPlatform {
+  public readonly target = "awscdk";
+  public newApp?(appProps: any): any {
+    return new App({
+      ...appProps,
+      stackFactory: (app: cdk.App, stackName: string) => {
+        // customize here!
+        return new cdk.Stack(app, stackName);
+      }
+    });
+  }
+}
+```
diff --git a/docs/docs/055-platforms/sim.md b/docs/docs/055-platforms/sim.md
@@ -0,0 +1,35 @@
+---
+title: Wing Cloud Simulator
+id: sim
+sidebar_label: sim
+description: Simulator Platform
+keywords: [Wing reference, Wing language, language, Wing language spec, Wing programming language, simulator, sim, wing simulator]
+---
+
+The Wing Cloud Simulator is a tool for running Wing applications on a single host. It offers a
+simple localhost implementation of all the resources of the Wing Cloud Library to allow developers
+to develop and functionally test cloud applications without having to deploy to the cloud.
+
+The `sim` [platform]((../02-concepts/03-platforms.md)) compiles your program so it can run in the
+Wing Cloud Simulator.
+
+## Usage
+
+```sh
+$ wing compile [entrypoint] --platform sim
+```
+
+## Parameters
+
+No parameters.
+
+## Output
+
+The output will be found under `target/<entrypoint>.wsim`.
+
+## Deployment
+
+The Wing Simulator can be used in one of these methods:
+
+* Interactively through the [Wing Console](/docs/start-here/local)
+* Using the `wing run|it target/<entrypoint>.wsim` command through the Wing CLI.
diff --git a/docs/docs/055-platforms/tf-aws.md b/docs/docs/055-platforms/tf-aws.md
@@ -0,0 +1,47 @@
+---
+title: Terraform/AWS
+id: tf-aws
+sidebar_label: tf-aws
+description: Terraform/AWS platform
+keywords: [Wing reference, Wing language, language, Wing language spec, Wing programming language, cli, terraform, aws, tf-aws, tfaws, amazon web services, platform]
+---
+
+The `tf-gcp` [platform](../02-concepts/03-platforms.md) compiles your program for Terraform and run on AWS.
+
+## Usage
+
+```sh
+$ wing compile --platform tf-aws [entrypoint]
+```
+
+## Parameters
+
+The `tf-aws` platform supports the following parameters (in `wing.toml`):
+
+* `vpc` - Determine whether to create a new VPC or use an existing one. Allowed values: `"new"` or `"existing"`.
+* `private_subnet_ids` (array of strings) - If using an existing VPC, provide the private subnet IDs.
+* `public_subnet_ids` (array of strings) - If using an existing VPC, provide the public subnet IDs.
+* `vpc_api_gateway` (boolean) - Whether Api gateways should be deployed in a VPC.
+* `vpc_lambda` (boolean) - Whether Lambda functions should be deployed in a VPC.
+
+Example `wing.toml`:
+
+```toml
+[ tf-aws ]
+vpc = "new"
+vpc_lambda = true
+vpc_api_gateway = true
+vpc_id = "vpc-123xyz"
+private_subnet_ids = ["subnet-123xyz"]
+public_subnet_ids = ["subnet-123xyz"]
+```
+
+
+## Output
+
+The output includes both a Terraform configuration file (under `target/cdktf.out/stacks/root`) and
+JavaScript bundles that include inflight code that executes on compute platform such as AWS Lambda.
+
+## Deployment
+
+You can deploy your stack to AWS using Terraform ([instructions](/docs/start-here/aws)).
diff --git a/docs/docs/055-platforms/tf-azure.md b/docs/docs/055-platforms/tf-azure.md
@@ -0,0 +1,28 @@
+---
+title: Terraform/Azure
+id: tf-azure
+sidebar_label: tf-azure
+description: Terraform/Azure platform
+keywords: [Wing reference, Wing language, language, Wing language spec, Wing programming language, cli, terraform, tf-azure, azure, microsoft azure, platform]
+---
+
+The `tf-azure` [platform](../02-concepts/03-platforms.md) compiles your program for Terraform and run on Azure.
+
+## Usage
+
+```sh
+$ export AZURE_LOCATION="East US"
+$ wing compile [entrypoint] --platform tf-azure
+```
+
+## Parameters
+
+The environment variable `AZURE_LOCATION` is required and indicates the [deployment
+location](https://github.com/claranet/terraform-azurerm-regions/blob/master/REGIONS.md) of your
+stack.
+
+## Output
+
+The output includes both a Terraform configuration file (under `target/cdktf.out/stacks/root`) and
+JavaScript bundles that include inflight code that executes on compute platform such as Azure
+Functions.
diff --git a/docs/docs/055-platforms/tf-gcp.md b/docs/docs/055-platforms/tf-gcp.md
@@ -0,0 +1,29 @@
+---
+title: Terraform/GCP
+id: tf-gcp
+sidebar_label: tf-gcp
+description: Terraform/GCP platform
+keywords: [Wing reference, Wing language, language, Wing language spec, Wing programming language, cli, terraform, tf-gcp, gcp, google cloud platform, platform]
+---
+
+The `tf-gcp` [platform](../02-concepts/03-platforms.md) compiles your program for Terraform and run on Google Cloud Platform.
+
+## Usage
+
+```sh
+$ export GOOGLE_PROJECT_ID="my-project"
+$ export GOOGLE_STORAGE_LOCATION="US"
+$ wing compile [entrypoint] --platform tf-gcp
+```
+
+## Parameters 
+
+The environment variable `GOOGLE_STORAGE_LOCATION` is required and indicates the [deployment
+location](https://cloud.google.com/storage/docs/locations) of all storage
+resources (such as buckets and queues). 
+
+The environment variable `GOOGLE_PROJECT_ID` is required and indicates
+the project ID of your stack.
+
+The output includes both a Terraform configuration file (under `target/cdktf.out/stacks/root`) and
+JavaScript bundles that include inflight code that executes on compute platform such as Google Cloud Functions.
diff --git a/docs/docs/06-tools/01-cli.md b/docs/docs/06-tools/01-cli.md
@@ -70,108 +70,16 @@ By default, `wing compile` will look for exactly one file named `main.w` or endi
 
 :::
 
-The --platform option specifies the target platform to compile for. The default platform is `sim`.
-The following platforms are built-in:
+The --platform option (or `-t`) specifies the target platform to compile for. The default platform
+is `sim`.
 
-* `sim` - [Wing Simulator](#sim-target)
-* `tf-aws` - Terraform/AWS
-* `tf-azure` - Terraform/Azure
-* `tf-gcp` - Terraform/Google Cloud Platform
+You can use one of the built-in platform providers:
 
-### `sim` Platform
-
-The Wing program is going to be compiled for the Wing simulator (`.wsim`).
-
-Usage:
-
-```sh
-$ wing compile [entrypoint] --platform sim
-```
-
-The output will be found under `target/<entrypoint>.wsim` and can be opened in two ways:
-
-* Interactively through the [Wing Console](/docs/start-here/local)
-* Using the `wing run|it target/<entrypoint>.wsim` command through the Wing CLI.
-
-
-### `tf-aws` Platform
-
-Compiles your program for Terraform and run on AWS.
-
-Usage:
-
-```sh
-$ wing compile [entrypoint] --platform tf-aws
-```
-
-The output includes both a Terraform configuration file (under `target/cdktf.out/stacks/root`) and
-JavaScript bundles that include inflight code that executes on compute platform such as AWS Lambda.
-
-You can deploy your stack to AWS using Terraform ([instructions](/docs/start-here/aws)).
-
-
-
-### `tf-azure` Platform
-
-Compiles your program for Terraform and run on Azure.
-
-Usage:
-
-```sh
-$ export AZURE_LOCATION="East US"
-$ wing compile [entrypoint] --platform tf-azure
-```
-
-The variable `AZURE_LOCATION` is required and indicates the [deployment
-location](https://github.com/claranet/terraform-azurerm-regions/blob/master/REGIONS.md) of your
-stack.
-
-The output includes both a Terraform configuration file (under `target/cdktf.out/stacks/root`) and
-JavaScript bundles that include inflight code that executes on compute platform such as Azure
-Functions.
-
-### `tf-gcp` Platform
-
-Compiles your program for Terraform and run on Google Cloud Platform.
-
-Usage:
-
-```sh
-$ export GOOGLE_PROJECT_ID="my-project"
-$ export GOOGLE_STORAGE_LOCATION="US"
-$ wing compile [entrypoint] --platform tf-gcp
-```
-
-The variable `GOOGLE_STORAGE_LOCATION` is required and indicates the [deployment
-location](https://cloud.google.com/storage/docs/locations) of all storage
-resources (such as buckets and queues). The variable `GOOGLE_PROJECT_ID` is required and indicates
-the project ID of your stack.
-
-The output includes both a Terraform configuration file (under `target/cdktf.out/stacks/root`) and
-JavaScript bundles that include inflight code that executes on compute platform such as Google Cloud Functions.
-
-
-### `awscdk` Platform
-
-Compiles your program for AWS CDK with CloudFormation to run on AWS.
-
-Usage:
-
-```sh
-# npm init is only needed if you don't already have a package.json file
-$ npm init -y
-$ npm i @winglang/platform-awscdk
-$ export CDK_STACK_NAME="my-project"
-$ wing compile --platform @winglang/platform-awscdk [entrypoint]
-```
-
-The output includes both a AWS-CDK configuration file (under `target/<entrypoint>.awscdk`) and
-JavaScript bundles that include inflight code that executes on compute platforms such as AWS Lambda.
-
-You can deploy your stack to AWS by installing the [AWS CDK Toolkit](https://docs.aws.amazon.com/cdk/v2/guide/cli.html) and running:
-```sh
-$ cdk deploy --app target/app.awscdk
-```
+* [Wing Cloud Simulator](../055-platforms/sim.md) - `sim`
+* [Terraform/AWS](../055-platforms/tf-aws.md) - `tf-aws`
+* [Terraform/Azure](../055-platforms/tf-azure.md) - `tf-azure`
+* [Terraform/GCP](../055-platforms/tf-gcp.md) - `tf-gcp`
+* [AWS CDK](../055-platforms/awscdk.md) - `@winglang/platform-awscdk`
 
 ## Test: `wing test`