From 8bc21c200bbc17c6d859ce662a005bec7aa9f6cc Mon Sep 17 00:00:00 2001 From: Andrew Starr-Bochicchio Date: Wed, 3 Feb 2021 13:01:44 -0500 Subject: [PATCH] App platform documentation updates (#573) * docs: Updates for apps domain changes. * docs: Add image source to apps docs. * docs: Add job components to apps docs. * docs: Reorder components in app docs. * docs: Document app service internal ports. * Apply suggestions from code review Co-authored-by: Samuel Guyah Co-authored-by: Samuel Guyah --- docs/data-sources/app.md | 76 ++++++++++++++++++++++++++++------- docs/resources/app.md | 87 +++++++++++++++++++++++++++++++++------- 2 files changed, 134 insertions(+), 29 deletions(-) diff --git a/docs/data-sources/app.md b/docs/data-sources/app.md index 050dfea6e..f58d627f5 100644 --- a/docs/data-sources/app.md +++ b/docs/data-sources/app.md @@ -48,17 +48,23 @@ A `service` can contain: * `instance_size_slug` - The instance size to use for this component. * `instance_count` - The amount of instances that this component should be scaled to. * `http_port` - The internal port on which this service's run command will listen. -* `git` - A Git repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. +* `internal_ports` - A list of ports on which this service will listen for internal traffic. +* `git` - A Git repo to use as component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo_clone_url` - The clone URL of the repo. - `branch` - The name of the branch to use. * `github` - A GitHub repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. -* `gitlab` - A Gitlab repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. +* `gitlab` - A Gitlab repo to use as component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `image` - An image to use as the component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `registry_type` - The registry type. One of `DOCR` (DigitalOcean container registry) or `DOCKER_HUB`. + - `registry` - The registry name. Must be left empty for the `DOCR` registry type. Required for the `DOCKER_HUB` registry type. + - `repository` - The repository name. + - `tag` - The repository tag. Defaults to `latest` if not provided. * `env` - Describes an environment variable made available to an app competent. - `key` - The name of the environment variable. - `value` - The value of the environment variable. @@ -74,6 +80,36 @@ A `service` can contain: - `success_threshold` - The number of successful health checks before considered healthy. - `failure_threshold` - The number of failed health checks before considered unhealthy. +A `static_site` can contain: + +* `name` - The name of the component. +* `build_command` - An optional build command to run while building this component from source. +* `dockerfile_path` - The path to a Dockerfile relative to the root of the repo. If set, overrides usage of buildpacks. +* `source_dir` - An optional path to the working directory to use for the build. +* `environment_slug` - An environment slug describing the type of this app. +* `output_dir` - An optional path to where the built assets will be located, relative to the build context. If not set, App Platform will automatically scan for these directory names: `_static`, `dist`, `public`. +* `index_document` - The name of the index document to use when serving this static site. +* `error_document` - The name of the error document to use when serving this static site. +* `catchall_document` - The name of the document to use as the fallback for any requests to documents that are not found when serving this static site. +* `git` - A Git repo to use as component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `repo_clone_url` - The clone URL of the repo. + - `branch` - The name of the branch to use. +* `github` - A GitHub repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. + - `repo` - The name of the repo in the format `owner/repo`. + - `branch` - The name of the branch to use. + - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `gitlab` - A Gitlab repo to use as component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `repo` - The name of the repo in the format `owner/repo`. + - `branch` - The name of the branch to use. + - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `env` - Describes an environment variable made available to an app competent. + - `key` - The name of the environment variable. + - `value` - The value of the environment variable. + - `scope` - The visibility scope of the environment variable. One of `RUN_TIME`, `BUILD_TIME`, or `RUN_AND_BUILD_TIME` (default). + - `type` - The type of the environment variable, `GENERAL` or `SECRET`. +* `route` - An HTTP paths that should be routed to this component. + - `path` - Paths must start with `/` and must be unique within the app. + A `worker` can contain: * `name` - The name of the component @@ -84,52 +120,64 @@ A `worker` can contain: * `environment_slug` - An environment slug describing the type of this app. * `instance_size_slug` - The instance size to use for this component. * `instance_count` - The amount of instances that this component should be scaled to. -* `git` - A Git repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. +* `git` - A Git repo to use as component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo_clone_url` - The clone URL of the repo. - `branch` - The name of the branch to use. * `github` - A GitHub repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. -* `gitlab` - A Gitlab repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. +* `gitlab` - A Gitlab repo to use as component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `image` - An image to use as the component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `registry_type` - The registry type. One of `DOCR` (DigitalOcean container registry) or `DOCKER_HUB`. + - `registry` - The registry name. Must be left empty for the `DOCR` registry type. Required for the `DOCKER_HUB` registry type. + - `repository` - The repository name. + - `tag` - The repository tag. Defaults to `latest` if not provided. * `env` - Describes an environment variable made available to an app competent. - `key` - The name of the environment variable. - `value` - The value of the environment variable. - `scope` - The visibility scope of the environment variable. One of `RUN_TIME`, `BUILD_TIME`, or `RUN_AND_BUILD_TIME` (default). - `type` - The type of the environment variable, `GENERAL` or `SECRET`. -A `static_site` can contain: +A `job` can contain: * `name` - The name of the component +* `kind` - The type of job and when it will be run during the deployment process. It may be one of: + - `UNSPECIFIED`: Default job type, will auto-complete to POST_DEPLOY kind. + - `PRE_DEPLOY`: Indicates a job that runs before an app deployment. + - `POST_DEPLOY`: Indicates a job that runs after an app deployment. + - `FAILED_DEPLOY`: Indicates a job that runs after a component fails to deploy. * `build_command` - An optional build command to run while building this component from source. * `dockerfile_path` - The path to a Dockerfile relative to the root of the repo. If set, overrides usage of buildpacks. * `source_dir` - An optional path to the working directory to use for the build. +* `run_command` - An optional run command to override the component's default. * `environment_slug` - An environment slug describing the type of this app. -* `output_dir` - An optional path to where the built assets will be located, relative to the build context. If not set, App Platform will automatically scan for these directory names: `_static`, `dist`, `public`. -* `index_document` - The name of the index document to use when serving this static site. -* `error_document` - The name of the error document to use when serving this static site. -* `catchall_document` - The name of the document to use as the fallback for any requests to documents that are not found when serving this static site. -* `git` - A Git repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. +* `instance_size_slug` - The instance size to use for this component. +* `instance_count` - The amount of instances that this component should be scaled to. +* `git` - A Git repo to use as the component's source. The repository must be able to be cloned without authentication. Only one of `git`, `github` or `gitlab` may be set. - `repo_clone_url` - The clone URL of the repo. - `branch` - The name of the branch to use. -* `github` - A GitHub repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. +* `github` - A GitHub repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/github/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. -* `gitlab` - A Gitlab repo to use as component's source. Only one of `git`, `github` or `gitlab` may be set. +* `gitlab` - A Gitlab repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/gitlab/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `image` - An image to use as the component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `registry_type` - The registry type. One of `DOCR` (DigitalOcean container registry) or `DOCKER_HUB`. + - `registry` - The registry name. Must be left empty for the `DOCR` registry type. Required for the `DOCKER_HUB` registry type. + - `repository` - The repository name. + - `tag` - The repository tag. Defaults to `latest` if not provided. * `env` - Describes an environment variable made available to an app competent. - `key` - The name of the environment variable. - `value` - The value of the environment variable. - `scope` - The visibility scope of the environment variable. One of `RUN_TIME`, `BUILD_TIME`, or `RUN_AND_BUILD_TIME` (default). - `type` - The type of the environment variable, `GENERAL` or `SECRET`. -* `route` - An HTTP paths that should be routed to this component. - - `path` - Paths must start with `/` and must be unique within the app. A `database` can contain: diff --git a/docs/resources/app.md b/docs/resources/app.md index c8f45bcf4..b6c1e0809 100644 --- a/docs/resources/app.md +++ b/docs/resources/app.md @@ -62,7 +62,9 @@ resource "digitalocean_app" "mono-repo-example" { spec { name = "mono-repo-example" region = "ams" - domains = ["foo.example.com"] + domain { + name = "foo.example.com" + } # Build a Go project in the api/ directory that listens on port 3000 # and serves it at https://foo.example.com/api @@ -121,7 +123,14 @@ The following arguments are supported: * `spec` - (Required) A DigitalOcean App spec describing the app. - `name` - (Required) The name of the app. Must be unique across all apps in the same account. - `region` - The slug for the DigitalOcean data center region hosting the app. - - `domains` - A list of hostnames where the application will be available. + - `domain` - Describes a domain where the application will be made available. + * `name` - The hostname for the domain. + * `type` - The domain type, which can be one of the following: + - `DEFAULT`: The default .ondigitalocean.app domain assigned to this app. + - `PRIMARY`: The primary domain for this app that is displayed as the default in the control panel, used in bindable environment variables, and any other places that reference an app's live URL. Only one domain may be set as primary. + - `ALIAS`: A non-primary domain. + * `wildcard` - A boolean indicating whether the domain includes all sub-domains, in addition to the given domain. + * `zone` - If the domain uses DigitalOcean DNS and you would like App Platform to automatically manage it for you, set this to the name of the domain on your account. - `env` - Describes an app-wide environment variable made available to all components. * `key` - The name of the environment variable. * `value` - The value of the environment variable. @@ -141,17 +150,23 @@ A `service` can contain: * `instance_size_slug` - The instance size to use for this component. * `instance_count` - The amount of instances that this component should be scaled to. * `http_port` - The internal port on which this service's run command will listen. +* `internal_ports` - A list of ports on which this service will listen for internal traffic. * `git` - A Git repo to use as the component's source. The repository must be able to be cloned without authentication. Only one of `git`, `github` or `gitlab` may be set - `repo_clone_url` - The clone URL of the repo. - `branch` - The name of the branch to use. -* `github` - A GitHub repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/github/install). Only one of `git`, `github` or `gitlab` may be set. +* `github` - A GitHub repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/github/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. -* `gitlab` - A Gitlab repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/gitlab/install). Only one of `git`, `github` or `gitlab` may be set. +* `gitlab` - A Gitlab repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/gitlab/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `image` - An image to use as the component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `registry_type` - The registry type. One of `DOCR` (DigitalOcean container registry) or `DOCKER_HUB`. + - `registry` - The registry name. Must be left empty for the `DOCR` registry type. Required for the `DOCKER_HUB` registry type. + - `repository` - The repository name. + - `tag` - The repository tag. Defaults to `latest` if not provided. * `env` - Describes an environment variable made available to an app competent. - `key` - The name of the environment variable. - `value` - The value of the environment variable. @@ -167,6 +182,36 @@ A `service` can contain: - `success_threshold` - The number of successful health checks before considered healthy. - `failure_threshold` - The number of failed health checks before considered unhealthy. +A `static_site` can contain: + +* `name` - The name of the component. +* `build_command` - An optional build command to run while building this component from source. +* `dockerfile_path` - The path to a Dockerfile relative to the root of the repo. If set, overrides usage of buildpacks. +* `source_dir` - An optional path to the working directory to use for the build. +* `environment_slug` - An environment slug describing the type of this app. +* `output_dir` - An optional path to where the built assets will be located, relative to the build context. If not set, App Platform will automatically scan for these directory names: `_static`, `dist`, `public`. +* `index_document` - The name of the index document to use when serving this static site. +* `error_document` - The name of the error document to use when serving this static site. +* `catchall_document` - The name of the document to use as the fallback for any requests to documents that are not found when serving this static site. +* `git` - A Git repo to use as the component's source. The repository must be able to be cloned without authentication. Only one of `git`, `github` or `gitlab` may be set. + - `repo_clone_url` - The clone URL of the repo. + - `branch` - The name of the branch to use. +* `github` - A GitHub repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/github/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `repo` - The name of the repo in the format `owner/repo`. + - `branch` - The name of the branch to use. + - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `gitlab` - A Gitlab repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/gitlab/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `repo` - The name of the repo in the format `owner/repo`. + - `branch` - The name of the branch to use. + - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `env` - Describes an environment variable made available to an app competent. + - `key` - The name of the environment variable. + - `value` - The value of the environment variable. + - `scope` - The visibility scope of the environment variable. One of `RUN_TIME`, `BUILD_TIME`, or `RUN_AND_BUILD_TIME` (default). + - `type` - The type of the environment variable, `GENERAL` or `SECRET`. +* `route` - An HTTP paths that should be routed to this component. + - `path` - Paths must start with `/` and must be unique within the app. + A `worker` can contain: * `name` - The name of the component @@ -180,49 +225,61 @@ A `worker` can contain: * `git` - A Git repo to use as the component's source. The repository must be able to be cloned without authentication. Only one of `git`, `github` or `gitlab` may be set - `repo_clone_url` - The clone URL of the repo. - `branch` - The name of the branch to use. -* `github` - A GitHub repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/github/install). Only one of `git`, `github` or `gitlab` may be set. +* `github` - A GitHub repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/github/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. -* `gitlab` - A Gitlab repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/gitlab/install). Only one of `git`, `github` or `gitlab` may be set. +* `gitlab` - A Gitlab repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/gitlab/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `image` - An image to use as the component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `registry_type` - The registry type. One of `DOCR` (DigitalOcean container registry) or `DOCKER_HUB`. + - `registry` - The registry name. Must be left empty for the `DOCR` registry type. Required for the `DOCKER_HUB` registry type. + - `repository` - The repository name. + - `tag` - The repository tag. Defaults to `latest` if not provided. * `env` - Describes an environment variable made available to an app competent. - `key` - The name of the environment variable. - `value` - The value of the environment variable. - `scope` - The visibility scope of the environment variable. One of `RUN_TIME`, `BUILD_TIME`, or `RUN_AND_BUILD_TIME` (default). - `type` - The type of the environment variable, `GENERAL` or `SECRET`. -A `static_site` can contain: +A `job` can contain: * `name` - The name of the component +* `kind` - The type of job and when it will be run during the deployment process. It may be one of: + - `UNSPECIFIED`: Default job type, will auto-complete to POST_DEPLOY kind. + - `PRE_DEPLOY`: Indicates a job that runs before an app deployment. + - `POST_DEPLOY`: Indicates a job that runs after an app deployment. + - `FAILED_DEPLOY`: Indicates a job that runs after a component fails to deploy. * `build_command` - An optional build command to run while building this component from source. * `dockerfile_path` - The path to a Dockerfile relative to the root of the repo. If set, overrides usage of buildpacks. * `source_dir` - An optional path to the working directory to use for the build. +* `run_command` - An optional run command to override the component's default. * `environment_slug` - An environment slug describing the type of this app. -* `output_dir` - An optional path to where the built assets will be located, relative to the build context. If not set, App Platform will automatically scan for these directory names: `_static`, `dist`, `public`. -* `index_document` - The name of the index document to use when serving this static site. -* `error_document` - The name of the error document to use when serving this static site. -* `catchall_document` - The name of the document to use as the fallback for any requests to documents that are not found when serving this static site. +* `instance_size_slug` - The instance size to use for this component. +* `instance_count` - The amount of instances that this component should be scaled to. * `git` - A Git repo to use as the component's source. The repository must be able to be cloned without authentication. Only one of `git`, `github` or `gitlab` may be set - `repo_clone_url` - The clone URL of the repo. - `branch` - The name of the branch to use. -* `github` - A GitHub repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/github/install). Only one of `git`, `github` or `gitlab` may be set. +* `github` - A GitHub repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/github/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. -* `gitlab` - A Gitlab repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/gitlab/install). Only one of `git`, `github` or `gitlab` may be set. +* `gitlab` - A Gitlab repo to use as the component's source. DigitalOcean App Platform must have [access to the repository](https://cloud.digitalocean.com/apps/gitlab/install). Only one of `git`, `github`, `gitlab`, or `image` may be set. - `repo` - The name of the repo in the format `owner/repo`. - `branch` - The name of the branch to use. - `deploy_on_push` - Whether to automatically deploy new commits made to the repo. +* `image` - An image to use as the component's source. Only one of `git`, `github`, `gitlab`, or `image` may be set. + - `registry_type` - The registry type. One of `DOCR` (DigitalOcean container registry) or `DOCKER_HUB`. + - `registry` - The registry name. Must be left empty for the `DOCR` registry type. Required for the `DOCKER_HUB` registry type. + - `repository` - The repository name. + - `tag` - The repository tag. Defaults to `latest` if not provided. * `env` - Describes an environment variable made available to an app competent. - `key` - The name of the environment variable. - `value` - The value of the environment variable. - `scope` - The visibility scope of the environment variable. One of `RUN_TIME`, `BUILD_TIME`, or `RUN_AND_BUILD_TIME` (default). - `type` - The type of the environment variable, `GENERAL` or `SECRET`. -* `route` - An HTTP paths that should be routed to this component. - - `path` - Paths must start with `/` and must be unique within the app. A `database` can contain: