From eac49aa90d408abe2e14bac8bf542295e4640d81 Mon Sep 17 00:00:00 2001 From: Lionello Lunesu Date: Fri, 4 Apr 2025 11:04:40 -0700 Subject: [PATCH 1/6] Use default network --- ...-26-deploying-defang-with-defang-part-2.md | 4 +- docs/concepts/compose.md | 125 +++++++++--------- 2 files changed, 64 insertions(+), 65 deletions(-) diff --git a/blog/2025-03-26-deploying-defang-with-defang-part-2.md b/blog/2025-03-26-deploying-defang-with-defang-part-2.md index 3a30d3da8..729ee35b8 100644 --- a/blog/2025-03-26-deploying-defang-with-defang-part-2.md +++ b/blog/2025-03-26-deploying-defang-with-defang-part-2.md @@ -45,14 +45,14 @@ Some things we had to change: ```yaml domainname: defang.io networks: - public: + default: aliases: - www.defang.io ``` One other hiccup was that we used to do www to non-www redirects using S3. There are a few ways to switch that up, but for the time being we decided to use Next.js middleware. -Pretty soon after that, the site was up and running in an AWS account—with TLS, DNS, and both the `www` and root domains automatically configured. Pretty straightfoward! +Pretty soon after that, the site was up and running in an AWS account—with TLS, DNS, and both the `www` and root domains automatically configured. Pretty straightfoward! --- diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index a09e17b00..4f1b0982a 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -6,8 +6,8 @@ sidebar_position: 150 # Compose -Defang allows you to use `compose.yaml` files to deploy your application to the cloud. -The `compose.yaml` file is a simple way to define and run multi-container applications. +Defang allows you to use `compose.yaml` files to deploy your application to the cloud. +The `compose.yaml` file is a simple way to define and run multi-container applications. This file format may look familiar to you if you've used [Docker](https://docker.com). The [Compose Specification](https://github.com/compose-spec/compose-spec/blob/main/spec.md#compose-file) lets you define a platform-agnostic application designed as a set of containers which are configured to run together with shared resources. These applications may be destined for any [OCI](https://opencontainers.org/) Container Runtime. Defang does the heavy lifting to deploy to your favourite cloud platform using this file. @@ -19,20 +19,19 @@ You can create a `compose.yaml` file in the root of your project, or use the [`d When you run `defang compose up`, Defang will read your `compose.yaml` file and [deploy](./deployments.md) the services named in that file to the cloud. ## Example of a Compose File -Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang. +Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang. ```yaml services: service-example: image: nginx:latest # use one of: image (shown on this line) or build (shown below) - # build: + # build: # context: . # dockerfile: Dockerfile - ports: - - mode: ingress # specify ports to expose - target: 8080 - published: 8080 # this is useful for running locally - + ports: + - mode: ingress # specify ports to expose + target: 8080 + published: 8080 # this is useful for running locally ``` ## Compose Top-level Properties @@ -41,7 +40,7 @@ Here are a list of top-level properties of the [Compose specification](https://d ### `services` (Required) -The services defined in your application. +The services defined in your application. ```yaml services: @@ -49,18 +48,18 @@ services: # add service-level properties here ``` -:::info +:::info Defang identifies a service based on your username, project name, and the service name you've defined under the `services` property. See our [Services](/docs/concepts/services) page for more about how Defang resolves service names. ::: ### `networks` (Optional) -The networks defined in your application. This is commonly added together with a [service-level `networks`](#networks-1) property. +The networks defined in your application. This is commonly added together with a [service-level `networks`](#networks-1) property. ```yaml networks: - public: + default: # the "default" network is always created even if not specified ``` See our [Networking](/docs/concepts/networking) page for more. @@ -76,7 +75,7 @@ The volume mounts for a container, reusable across services. This feature is not ``` :::warning -Defang does not support the `secrets` top-level property. Please read our [Configuration](/docs/concepts/configuration) page for more. +Defang does not support the `secrets` top-level property. Please read our [Configuration](/docs/concepts/configuration) page for more. ::: ## Compose Service-level Properties @@ -86,14 +85,14 @@ Here are a list of service-level properties of the [Compose specification](https Service-level means inside your `service`. A service-level property called `build` would look like: ```yaml service: - build: ... + build: ... ``` Note that in your Compose file, you will need a top-level property called `services` to contain all of your services. For example: ```yaml services: - service: - build: ... + service: + build: ... ``` ::: @@ -103,9 +102,9 @@ services: The [build configuration](https://github.com/compose-spec/compose-spec/blob/main/build.md). This property describes how to create an OCI container for this service. ```yaml -build: - context: . - dockerfile: ./Dockerfile + build: + context: . + dockerfile: ./Dockerfile ``` ### `image` @@ -114,7 +113,7 @@ build: [This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#image) describes the image from which your container should start. ```yaml -image: nginx:latest + image: nginx:latest ``` ### `ports` @@ -123,23 +122,23 @@ image: nginx:latest The ports to expose. The default port mode is `ingress`. ```yaml -ports: - - mode: ingress - target: 80 - published: 80 + ports: + - mode: ingress + target: 80 + published: 80 ``` :::info -Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker. +Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker. ::: ### `command` (Optional) -The command which will be run to start your service. If left out, the command from the Docker image will be used. +The command which will be run to start your service. If left out, the command from the Docker image will be used. ```yaml -command: nginx -g 'daemon off;' + command: nginx -g 'daemon off;' ``` ### `deploy` @@ -148,21 +147,21 @@ command: nginx -g 'daemon off;' The [Deploy Specification](https://github.com/compose-spec/compose-spec/blob/main/deploy.md) describes the runtime constraints and requirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.). ```yaml -deploy: - replicas: 1 - reservations: - cpus: '0.5' - memory: 256M + deploy: + replicas: 1 + reservations: + cpus: '0.5' + memory: 256M ``` ### `depends_on` (Not yet supported) -This property describes startup dependencies between services. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. +This property describes startup dependencies between services. This feature currently has limited supported by Defang, but can be useful in local development with Docker. ```yaml -# depends_on: -# - db + # depends_on: + # - db ``` ### `environment` @@ -170,12 +169,12 @@ This property describes startup dependencies between services. This feature is c The environment variables to set. ```yaml -environment: - DATABASE_USER: someuser + environment: + DATABASE_USER: someuser ``` :::info For sensitive environment variables (or secret values), you should list the variable's name with a blank or `null` value, and then securely set their actual value with `defang config` in the CLI. See our [Configuration page](/docs/concepts/configuration) for more. - + For example: ```yaml - DATABASE_USER=someuser # env var loaded with this literal value @@ -191,54 +190,54 @@ For sensitive environment variables (or secret values), you should list the vari When using Defang, your Compose file must have a healthcheck if you want to expose an `ingress` port—even if your Dockerfile already contains one. :::note -`curl` is commonly used for containers with an Ubuntu-based image, and `wget` is used for containers with an `alpine`-based image. +`curl` is commonly used for containers with an Ubuntu-based image, and `wget` is used for containers with an `alpine`-based image. ::: ```yaml -healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8080/"] - interval: 30s - timeout: 90s - retries: 3 + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/"] + interval: 30s + timeout: 90s + retries: 3 ``` or ```yaml -healthcheck: - test: ["CMD", "wget", "--spider", "http://localhost:8080/"] - interval: 30s - timeout: 90s - retries: 3 + healthcheck: + test: ["CMD", "wget", "--spider", "http://localhost:8080/"] + interval: 30s + timeout: 90s + retries: 3 ``` ### `networks` (Optional) -The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. To avoid warnings, add this to the [top-level `networks`](#networks) property as well. +The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. To avoid warnings, add this to the [top-level `networks`](#networks) property as well. ```yaml -networks: - public: + networks: + default: # when not specified, services are assigned to the default network ``` You can also assign an alias for a network by using `aliases`, as seen below: ```yaml -networks: - public: - aliases: - - app + networks: + default: + aliases: + - app ``` - + See our [Networking](/docs/concepts/networking) page for more. - + ### `restart` (Optional, but highly recommended) -The restart mode for a container. Defaults to `unless-stopped` unless otherwise specified. +The restart mode for a container. Defaults to `unless-stopped` unless otherwise specified. ```yaml -restart: unless-stopped + restart: unless-stopped ``` ### `volumes` @@ -247,6 +246,6 @@ restart: unless-stopped The volume mounts for a container, specific to a service. This feature is not currently supported by Defang. ```yaml -# volumes: -# - "./backend:/app" + # volumes: + # - "./backend:/app" ``` From a8ce7b77ee415c14ec0ae8c0016b77ba8ee78e97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lio=E6=9D=8E=E6=AD=90?= Date: Fri, 4 Apr 2025 11:21:20 -0700 Subject: [PATCH 2/6] Update networking.mdx for networks --- docs/concepts/networking.mdx | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/concepts/networking.mdx b/docs/concepts/networking.mdx index 6b3c5cd99..3167e30e3 100644 --- a/docs/concepts/networking.mdx +++ b/docs/concepts/networking.mdx @@ -16,7 +16,7 @@ This page is about internal networking only. If you want to configure your servi ## Internal Communication -You can expose ports in your service definition to allow other services to communicate with it. Similar to public communication, you can use the `ports` section of your service definition, but set the `mode` to `host` instead of `ingress` to allow other services to communicate with it through the internal network. +You can expose ports in your service definition to allow other services to communicate with it. Similar to public communication, you can use the `ports` section of your service definition. Set the `mode` to `host` (instead of the default `ingress`) to be able to connect to the container directly, avoiding the need of a load balancer. ### Sample Configuration @@ -66,3 +66,35 @@ http://: ``` + +### Networks + +The Compose spec has a notion of [networks](https://github.com/compose-spec/compose-spec/blob/main/06-networks.md). By default, each service gets added to the `default` network. Networks in Compose can be flagged as `internal`, but this means they have no connection to the outside world at all (no egress). + +Only services in the `default` network can have public IPs. Services in any other network will be in a private subnet. + +```yaml +services: + frontend: + build: ./fe + ports: + - 80 # load-balanced, ie. mode: ingress + networks: + default: + private: + + backend: + build: ./be + ports: + - mode: host # no load balancer + target: 8080 + networks: + private: + +networks: + default: + private: + internal: true # no egress +``` + + From a93ea3951668e8efcca911e51b4d2d878742351b Mon Sep 17 00:00:00 2001 From: Lionello Lunesu Date: Fri, 4 Apr 2025 12:53:59 -0700 Subject: [PATCH 3/6] PR comment --- docs/concepts/compose.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 4f1b0982a..ab8edb5ac 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -214,11 +214,12 @@ or ### `networks` (Optional) -The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. To avoid warnings, add this to the [top-level `networks`](#networks) property as well. +The service network configuration. By default, Compose will add services to the `default` network, which has external connectivity. +You can also add services to private networks. To avoid warnings, you should add them to the [top-level `networks`](#networks) property as well. ```yaml networks: - default: # when not specified, services are assigned to the default network + default: # when not specified, services are assigned to the "default" network ``` You can also assign an alias for a network by using `aliases`, as seen below: From f66b95ca7cf47a1e463ac51884176e5a0286f988 Mon Sep 17 00:00:00 2001 From: Lionello Lunesu Date: Fri, 11 Apr 2025 11:56:09 -0700 Subject: [PATCH 4/6] Reconcile comments --- docs/concepts/networking.mdx | 147 +++++++++++++++++++++-------------- 1 file changed, 88 insertions(+), 59 deletions(-) diff --git a/docs/concepts/networking.mdx b/docs/concepts/networking.mdx index 3167e30e3..676605ba9 100644 --- a/docs/concepts/networking.mdx +++ b/docs/concepts/networking.mdx @@ -1,5 +1,5 @@ --- -title: Networking +title: Networking description: Defang helps you safely configure your services' networking. sidebar_position: 300 --- @@ -8,70 +8,18 @@ import TabItem from '@theme/TabItem'; # Networking -Defang configures Security Groups, deploys applications to a private subnet and uses an Application Load Balancer to route traffic to your services from the public internet only when required. +By default, Defang configures your application's networking and security groups to follow secure best practices. +We also configure load-balancers and public IP addresses when appropriate. The following sections describe how to configure different network and security group topologies. :::tip -This page is about internal networking only. If you want to configure your services to be accessible from the public internet, check the [Domains page](./domains.mdx). +This page is about complex networking. If you want to configure your services to be accessible from the public internet, check the [Domains page](./domains.mdx). ::: -## Internal Communication +## Networks -You can expose ports in your service definition to allow other services to communicate with it. Similar to public communication, you can use the `ports` section of your service definition. Set the `mode` to `host` (instead of the default `ingress`) to be able to connect to the container directly, avoiding the need of a load balancer. +The Compose spec has a notion of [networks](https://github.com/compose-spec/compose-spec/blob/main/06-networks.md). By default, each service gets added to the `default` network. Networks in Compose can be flagged as `internal`, but this means they have no connection to the outside world at all (no egress). -### Sample Configuration - - - -```yaml -services: - # [...] - service1: - ports: - - mode: host - target: 3000 - app_protocol: http -``` - - -```typescript -const service = new defang.DefangService("service1", { - // [...] - ports: [{ - target: 3000, - mode: "host", - protocol: "http", - }], -}); -``` - - - -### Internal DNS - -Internal communication is handled slightly differently between the Defang Playground and Defang BYOC. - - - -Internal communication between services in the Defang Playground follows the following pattern: - -``` -http://-: -``` - - -Internal communication between services in Defang BYOC follows the following pattern: - -``` -http://: -``` - - - -### Networks - -The Compose spec has a notion of [networks](https://github.com/compose-spec/compose-spec/blob/main/06-networks.md). By default, each service gets added to the `default` network. Networks in Compose can be flagged as `internal`, but this means they have no connection to the outside world at all (no egress). - -Only services in the `default` network can have public IPs. Services in any other network will be in a private subnet. +Only services in the `default` network can have public IPs. Services in any other network will be in a private subnet. ```yaml services: @@ -97,4 +45,85 @@ networks: internal: true # no egress ``` +### Public Services + +By default, services will be in the `default` network and behind a public load-balancer, ie. exposed ports default to `mode: ingress`: + +```yaml +services: + web: + networks: + default: # this is the default, so no need to specify + ports: + - 80:80 # Defang will use a public load-Balancer +``` + +If you want a service to have a public IP address, ensure it's in the `default` network (the default) and +set the port to `mode: host`: + +```yaml +services; + web: + ports: + - target: 80 + mode: host # Defang will assign a public IP +``` +### Private Services +If you want a service with exposed ports to not be accessible from the public internet, create a private network: + +```yaml +services: + web: # this service can receive public traffic and communicate to private services + ports: + - 80 + networks: + default: + private: + db: # this service can only receive traffic from other services in the same network + ports: + - 1234 + networks: + private: +networks: + private: # any network that's not "default" is considered private +``` + +The service's hostname will be the same as the service's name, in this case `db`. + +## Hostname Aliases + +By using network aliases, a service can be made available at multiple hostnames. + +```yaml +services: + web: + domainname: example.com + networks: + default: + aliases: + - www.example.com # a public alias +``` + +### Internal DNS + +Internal communication is handled slightly differently between the Defang Playground and Defang BYOC. + + + +Internal communication between services in the Defang Playground follows the following pattern: + +``` +http://-: +``` + +The Defang CLI applies the `` prefix when it detects service names in the values of environment variables. + + +Internal communication between services in Defang BYOC follows the following pattern: + +``` +http://: +``` + + From 70f41005a9cd4f017e936a2b545c307154c7b37b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lio=E6=9D=8E=E6=AD=90?= Date: Fri, 11 Apr 2025 12:27:09 -0700 Subject: [PATCH 5/6] Update docs/concepts/networking.mdx Co-authored-by: Jordan Stephens --- docs/concepts/networking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/networking.mdx b/docs/concepts/networking.mdx index 676605ba9..beed6822c 100644 --- a/docs/concepts/networking.mdx +++ b/docs/concepts/networking.mdx @@ -47,7 +47,7 @@ networks: ### Public Services -By default, services will be in the `default` network and behind a public load-balancer, ie. exposed ports default to `mode: ingress`: +By default, services will be in the `default` network. By default these services are not accessible directly, but may be accessed through a public load-balancer, ie. exposed ports default to `mode: ingress`: ```yaml services: From a0fe7852dbd4963ec920cb2e90b33efaf4008167 Mon Sep 17 00:00:00 2001 From: Lionello Lunesu Date: Fri, 11 Apr 2025 13:24:43 -0700 Subject: [PATCH 6/6] PR comments --- docs/concepts/networking.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/concepts/networking.mdx b/docs/concepts/networking.mdx index beed6822c..f609f42fe 100644 --- a/docs/concepts/networking.mdx +++ b/docs/concepts/networking.mdx @@ -17,9 +17,9 @@ This page is about complex networking. If you want to configure your services to ## Networks -The Compose spec has a notion of [networks](https://github.com/compose-spec/compose-spec/blob/main/06-networks.md). By default, each service gets added to the `default` network. Networks in Compose can be flagged as `internal`, but this means they have no connection to the outside world at all (no egress). - -Only services in the `default` network can have public IPs. Services in any other network will be in a private subnet. +The Compose spec has a notion of [networks](https://github.com/compose-spec/compose-spec/blob/main/06-networks.md). By default, each service gets added to the `default` network. +Services in the `default` network can have public IPs. Services in any other network will be in a private subnet. +These services cannot be reached from outside the network, but they can still make network requests to the public internet. ```yaml services: