feat(vpc): add first use case

menu/navigation.json

@@ -2950,6 +2950,11 @@
                     "label": "Getting the most from Private Networks",
                     "slug": "getting-most-private-networks"
                   },
+                  {
+
+                    "label": "VPC use case 1: basic infrastructure",
+                    "slug": "use-case-basic"
+                  },
                   {
                     "label": "Understanding VPC GA and migration",
                     "slug": "vpc-migration"

network/vpc/how-to/create-private-network.mdx

@@ -48,6 +48,10 @@ While DHCP is built into all new Private Networks, it may not be automatically a
 
 6. Click **Create Private Network** to finish. Your Private Network is created.
 
+<Message type="tip">
+See our [Basic VPC use case](/network/vpc/reference-content/use-case-basic/) documentation for full details of how to create a simple infrastructure that leverages the advantages of Private Networks, including accompanying Terraform templates.
+</Message>
+
 ## How to configure CIDR
 
 Private Networks have built-in **D**ynamic **H**ost **C**onfiguration **P**rotocol (DHCP). DHCP manages the allocation of private IP addresses to resources attached to the network. For this purpose, a **C**lassless **I**nter-**D**omain **R**outing (CIDR) block is defined for each Private Network, from which IP addresses will be assigned. In fact, both an IPv4 and an IPv6 CIDR block are defined.

network/vpc/index.mdx

@@ -6,9 +6,10 @@ meta:
 
 <Alert
   sentiment="info"
-  title="Getting the most from your Private Networks"
+  title="VPC Basic Use Case"
 >
-  Learn how to optimize your Scaleway VPCs, Private Networks and resource connectivity with [our new guide](/network/vpc/reference-content/getting-most-private-networks/) detailing tips and best practices.
+  Read our [Basic VPC use case](/network/vpc/reference-content/use-case-basic/) documentation for full details of how to create a simple infrastructure that leverages the advantages of Private Networks, including accompanying Terraform templates.
+
 </Alert>
 
 <ProductHeader 

network/vpc/reference-content/getting-most-private-networks.mdx

@@ -49,6 +49,10 @@ For example, you may use one Private Network for frontend resources and another
 
 When [creating a Private Network](/network/vpc/how-to/create-private-network/), you can let Scaleway automatically generate a CIDR block for it that is guaranteed to be unique in this VPC. All resources attached to the Private Network get a private IP address from this block. However, you also have the option to define your own CIDR block for the network. Ensure you choose a prefix and network size that is appropriate for your needs, does not overlap with that of any other Private Network in the VPC, and contains enough IP addresses for all resources that will be attached to the Private Network.
 
+<Message type="tip">
+See our [Basic VPC use case](/network/vpc/reference-content/use-case-basic/) documentation for full details of how to create a simple infrastructure that leverages the advantages of Private Networks, including accompanying Terraform templates.
+</Message>
+
 ## Attaching resources to Private Networks
 
 When you attach a resource (e.g. an Instance, an Elastic Metal server) to a Private Network, you can either:

network/vpc/reference-content/use-case-basic.mdx

@@ -0,0 +1,127 @@
+---
+meta:
+  title: VPC use case 1 - Basic infrastructure to leverage VPC isolation
+  description: Learn how to set up a basic infrastructure using VPC isolation for secure cloud environments. Step-by-step guidance on leveraging VPCs for optimal network isolation.
+content:
+  h1: VPC use case 1 - Basic infrastructure to leverage VPC isolation
+  paragraph: Learn how to set up a basic infrastructure using VPC isolation for secure cloud environments. Step-by-step guidance on leveraging VPCs for optimal network isolation.
+tags: vpc private-network connectivity best-practice use-case infrastructure-diagram
+dates:
+  validation: 2025-01-16
+  posted: 2025-01-16
+categories:
+  - network
+---
+
+Scaleway **V**irtual **P**rivate **N**etwork (VPC) and the accompanying range of network products, are important building blocks within the Scaleway ecosystem. By creating your Scaleway resources within a carefully thought out VPC-based infrastructure, you can maximize security, resilience and efficiency. 
+
+Knowing how to create, combine and configure resources such as Private Networks with definable subnets, VPC routing with custom routes, IPAM to define and manage your IP addresses, and resources such as Load Balancers and Public Gateways to facilitate connectivity and traffic distribution, is invaluable in achieving control over your networking environment.
+
+This is the first in a series of use cases designed to show you potentially interesting and useful infrastructures, illustrating how to use VPC and other network products to achieve a robust, secure and scalable cloud environment. 
+
+[Terraform templates](https://github.com/scaleway/terraform-examples/tree/main/demo-vpc-app) accompany each use case.
+
+## Overview
+
+The architecture diagram below shows the infrastructure for this use-case.
+
+<Lightbox src="scaleway-vpc-infra-1.webp" size="large" alt="An architecture diagram shows how a Load Balancer inside a Scaleway VPC is attached to a Private Network. Also attached to the Private Network are three Instances (connected to Block Storage), a Managed Database, and a Public Gateway." />
+
+This is a basic infrastructure to leverage VPC isolation:
+
+- [Instances](/compute/instances/concepts/#instance) are hosting the application without having their own [public/flexible IP addresses](/compute/instances/concepts/#flexible-ip).
+- [Managed Database](/managed-databases/postgresql-and-mysql/concepts/#managed-database) is accessed by the Instances over the Private Network only, with no exposure to the public internet.
+- [Load Balancer](/network/load-balancer/concepts/) distributes user traffic to the Instances over the Private Network.
+- Administrators can access the Instances via the [Public Gateway](/network/public-gateways/concepts/#public-gateway).
+- External services are accessed by the Instances via the Public Gateway.
+
+Full [Terraform templates](#terraform) are available for this infrastructure.
+
+## Detail
+
+User requests go via a domain name, whose DNS record points to the public flexible IP of a Scaleway Load Balancer. This Load Balancer is attached to a **Private Network** in a **VPC**. It distributes user traffic to multiple **Instances** which are also attached to the Private Network, and do not have their own public/flexible IP addresses. These Instances are accessible only from within the VPC. The Instances can store data to and retrieve data from **Block Storage** and a **Managed Database** attached to the same Private Network and not exposed to the internet. 
+
+The **Public Gateway** attached to the Private Network has its own public flexible IP address, and administrators can use solutions such as SSH bastion to connect to Instances via the Public Gateway for maintenance and administrative tasks. The Public Gateway also provides secure access to the public internet should the Instances need to download package updates, for example. Finally, the Public Gateway also allows the Instances to access services outside the VPC, e.g. those hosted on other Scaleway resources which are not compatible with VPC, via their public endpoints.
+
+## Advantages
+
+### Isolation and security
+
+Resources are isolated within a VPC, and public IP exposure is restricted to Load Balancer and Public Gateway. This enhances security, ensuring that only authorized services and users can access the VPC's resources, and reducing exposure to external threats. Any sensitive data stored on the Instances and Managed Databases is kept within the VPC, and not exposed to the public internet.
+
+### Scalability and reliability
+
+Use of the Load Balancer to distribute traffic across multiple Instances enhances reliability. If the Load Balancer's built-in health checks register that one Instance is down, it is able to immediately redirect traffic to the remaining healthy Instances only, ensuring high availability. Additional Instances can be spun up and added to the Load Balancer's backend at any time, facilitating on-demand scalability.
+
+External services like Transactional Email, Serverless, and NATS, Queues, Topics, and Events are also highly scalable, flexibly facilitating event-driven architectures and asynchronous processing.
+
+### Controlled access
+
+The Public Gateway, with its public IP address, allows controlled access between the public internet and the VPC. Features such as SSH bastion allow selected administrators with the correct credentials to connect to resources within the VPC, and static NAT and/or advertisement of a default route provides the ability to direct traffic through the gateway to and from the resources within.
+
+### Cost control
+
+Creating Scaleway resources without their own public IP addresses saves money, as these addresses are billed resources, while the creation, configuration and assignment of IP addresses from a Private Network is free of charge. 
+
+## Applications
+
+This kind of infrastructure is appropriate for many applications, including but not limited to:
+- **E-commerce platforms**: A scalable backend (Instances, Block Storage), which can securely connect to payment systems and privately-accessed user data (Managed Database), with public-facing components (Load Balancer) for appropriately handling user traffic.
+- **Web applications**: Web applications that routinely need to handle high traffic are ideally suited to the solution of a Load Balancer in front of a horizontally scalable set of Instances, to facilitate uptime and high availability and grow with demand.
+- **Enterprise applications**: Enterprises handling sensitive data (e.g. HR systems) can benefit from the isolation and security of a VPC, with all of its additional features, to keep internal services running without unnecessary exposure to the internet.
+
+## Tutorial
+
+Follow the steps below to create this infrastructure using the [Scaleway console](https://console.scaleway.com/organization):
+
+1. [Create a VPC](/network/vpc/how-to/create-vpc/) (or use the [default VPC](/network/vpc/how-to/create-vpc/#how-to-identify-your-default-vpcs) pre-created for each Scaleway Project in the appropriate [region](/network/vpc/concepts/#region-and-availability-zone)).
+2. [Create a Private Network](/network/vpc/how-to/create-private-network/) inside the VPC. You can either let Scaleway create the network with an auto-generated subnet, which will provide the private IP addresses for attached resources, or specify a self-defined subnet.
+3. [Create a Public Gateway](/network/public-gateways/how-to/create-a-public-gateway/) (set it to advertise the [default route](/network/public-gateways/concepts/#default-route)) and [attach it to the Private Network](/network/public-gateways/how-to/configure-a-public-gateway/#how-to-attach-a-public-gateway-to-a-private-network).
+4. [Set up SSH bastion](/network/public-gateways/how-to/use-ssh-bastion/) on the Public Gateway, to allow administrator access.
+5. [Create a Managed Database](/managed-databases/postgresql-and-mysql/how-to/create-a-database/).
+6. [Detach the Managed Database's public endpoint](/managed-databases/postgresql-and-mysql/how-to/remove-public-endpoint/) and [attach it to the Private Network](/managed-databases/postgresql-and-mysql/how-to/connect-database-private-network/) you created in step 2.
+7. Create and configure external services as required, e.g. [Object Storage](/storage/object/quickstart/), [Transactional Email](/managed-services/transactional-email/quickstart/) and [Secret Manager](/identity-and-access-management/secret-manager/quickstart/).
+8. [Create your Instances](/compute/instances/how-to/create-an-instance/), using the configuration best-suited to your application. Do not assign public IPv4 or IPv6 addresses to the Instances. Add Block Storage volumes as required (or you can create and attach these [later](/storage/block/quickstart/).)
+    <Message type="tip">
+    If you are creating several Instances with the exact same configuration running the exact same template, consider creating just one Instance, configuring and installing it to communicate with the other resources inside and outside the VPC as required, then [creating an image](/compute/instances/how-to/create-a-backup/) of this Instance and creating the remaining Instances [using this image](/compute/instances/how-to/create-a-backup/#how-to-create-or-restore-an-instance-from-an-image).
+    </Message>
+9. [Attach each Instance to the Private Network](/compute/instances/how-to/use-private-networks/#how-to-attach-instances-to-an-existing-private-network) you created at step 2. Either let Scaleway automatically choose an IP from the Private Network's subnet for each Instance, or use [reserved IPs](s/network/ipam/how-to/reserve-ip/) to specify the IP for each Instance on the network.
+10. [Create a Load Balancer](/network/load-balancer/how-to/create-load-balancer/), ensuring you assign a public (flexible) IP address. Do not yet create the frontends and backends.
+11. [Attach the Load Balancer to the Private Network](/network/load-balancer/how-to/use-with-private-network/#how-to-attach-a-private-network-to-your-load-balancer). As before, you can use an auto-selected IP, or a specific reserved IP from the subnet.
+12. [Create a frontend and backend for the Load Balancer](/network/load-balancer/how-to/create-frontends-backends/). Choose the most appropriate configuration for your purpose and application, following advice and tips in the linked documentation. When configuring the Load Balancer's backend servers, enter the private IP addresses of the Instances on the Private Network.
+13. [Create your domain](/network/domains-and-dns/how-to/register-internal-domain/) and [add a DNS record](/network/domains-and-dns/how-to/manage-dns-records/#how-to-add-dns-records) (e.g. an A record) to point it to the public IP of your Load Balancer. While instructions show how to do this with Scaleway's **Domains and DNS** product, you can also use an external domain and configure it with another provider.
+
+## Terraform
+
+Terraform templates for this architecture are provided in full on our [Scaleway Terraform Examples repo](https://github.com/scaleway/terraform-examples/tree/main/demo-vpc-app/). Terraform allows you to create Infrastructure as Code (IaC) to build, configure and manage your infrastructure with configuration files, rather than with the Scaleway console. 
+
+The templates include an example "Task Tracker" application to show how the infrastructure is used. The application is containerized using Docker, deployed on an Instance in the Private Network and leverages PostgreSQL for data storage. Full instructions are provided for creating the infrastructure with Terraform and deploying the test application.
+
+The following snippet shows an extract of one of the templates:
+
+```
+resource "scaleway_vpc" "vpc01" {
+  name = "vpc_${var.app_name}"
+}
+
+resource "scaleway_vpc_private_network" "pn01" {
+  name   = "pn_${var.app_name}"
+  vpc_id = scaleway_vpc.vpc01.id
+  ipv4_subnet {
+    subnet = local.subnet
+  }
+}
+
+resource "scaleway_vpc_public_gateway_ip" "gwip01" {
+}
+
+resource "scaleway_vpc_public_gateway" "pgw01" {
+  type            = "VPC-GW-S"
+  name            = "pgw_${var.app_name}"
+  ip_id           = scaleway_vpc_public_gateway_ip.gwip01.id
+  bastion_enabled = true
+  bastion_port    = 61000
+}
+```
+
+[See the full Terraform templates](https://github.com/scaleway/terraform-examples/tree/main/demo-vpc-app/)