diff --git a/docs/content/assets/img/getting-started/docker-router.png b/docs/content/assets/img/getting-started/docker-router.png new file mode 100644 index 000000000..3ff33493a Binary files /dev/null and b/docs/content/assets/img/getting-started/docker-router.png differ diff --git a/docs/content/assets/img/getting-started/kubernetes-gateway.png b/docs/content/assets/img/getting-started/kubernetes-gateway.png new file mode 100644 index 000000000..5d59d2c69 Binary files /dev/null and b/docs/content/assets/img/getting-started/kubernetes-gateway.png differ diff --git a/docs/content/assets/img/getting-started/providers.png b/docs/content/assets/img/getting-started/providers.png new file mode 100644 index 000000000..c1933b656 Binary files /dev/null and b/docs/content/assets/img/getting-started/providers.png differ diff --git a/docs/content/assets/img/getting-started/traefik-dashboard-docker.png b/docs/content/assets/img/getting-started/traefik-dashboard-docker.png new file mode 100644 index 000000000..82cbb53ad Binary files /dev/null and b/docs/content/assets/img/getting-started/traefik-dashboard-docker.png differ diff --git a/docs/content/assets/img/getting-started/traefik-dashboard.png b/docs/content/assets/img/getting-started/traefik-dashboard.png new file mode 100644 index 000000000..cccd73ef5 Binary files /dev/null and b/docs/content/assets/img/getting-started/traefik-dashboard.png differ diff --git a/docs/content/assets/img/getting-started/whoami-localhost.png b/docs/content/assets/img/getting-started/whoami-localhost.png new file mode 100644 index 000000000..79f059107 Binary files /dev/null and b/docs/content/assets/img/getting-started/whoami-localhost.png differ diff --git a/docs/content/getting-started/docker.md b/docs/content/getting-started/docker.md new file mode 100644 index 000000000..a5103cab5 --- /dev/null +++ b/docs/content/getting-started/docker.md @@ -0,0 +1,162 @@ +--- +title: "Docker and Traefik Quick Start" +description: "Deploy Traefik in Docker and expose your first service" +--- + +# Getting Started with Docker and Traefik + +Docker is a first-class citizen in Traefik, offering native support for Docker containers and services. +Whether you're using Docker Compose or running containers directly, Traefik provides a seamless experience for managing your Docker traffic. + +This guide shows you how to: + +- Install Traefik using Docker +- Expose the Traefik dashboard +- Deploy a sample application +- Configure basic routing + +## Prerequisites + +- Docker +- Docker Compose (optional) + +## Install Traefik + +### Using Docker Compose + +Create a Docker Compose file. +This configuration: + +- Exposes ports 80 and 8080. +- Enables the Docker provider +- Configures the dashboard with basic settings. Port 8080 serves the dashboard because we enabled `--api.insecure=true` (development use only) +- Mounts the Docker socket for container discovery + +```yaml +# docker-compose.yml +services: + traefik: + image: traefik:v3.4 + command: + - "--api.insecure=true" + - "--providers.docker=true" + - "--entrypoints.web.address=:80" + ports: + - "80:80" + - "8080:8080" + volumes: + - /var/run/docker.sock:/var/run/docker.sock +``` + +Start Traefik: + +```bash +docker-compose up -d +``` + +### Using Docker CLI + +Alternatively, you can run Traefik directly with Docker. +This command: + +- Exposes ports 80 and 8080 for web traffic and dashboard access +- Mounts the configuration file and Docker socket +- Uses the same configuration as the Docker Compose example + +Create a configuration file: + +```yaml +# traefik.yml +api: + insecure: true +entryPoints: + web: + address: ":80" +providers: + docker: {} +``` + +Start Traefik: + +```bash +docker run -d \ + -p 80:80 \ + -p 8080:8080 \ + -v $PWD/traefik.yml:/etc/traefik/traefik.yml \ + -v /var/run/docker.sock:/var/run/docker.sock \ + traefik:v3.4 +``` + +## Expose the Dashboard + +Because we explicitly enabled insecure mode, the [dashboard](../reference/install-configuration/api-dashboard.md) is reachable on port 8080 without authentication. +**Do not enable this flag in production**. + +You can access the dashboard at: + +[http://localhost:8080/dashboard/](http://localhost:8080/dashboard/) + +![Traefik Dashboard Screenshot](../assets/img/getting-started/traefik-dashboard.png) + +## Deploy a Sample Application + +Create a whoami service: + +```yaml +# whoami.yml +services: + whoami: + image: traefik/whoami + labels: + - "traefik.http.routers.whoami.rule=Host(`whoami.localhost`)" +``` + +Apply the configuration: + +```bash +docker-compose -f whoami.yml up -d +``` + +## Test Your Setup + +You can use the following curl command to verify that the application is correctly exposed: + +```bash +curl http://whoami.localhost + +Hostname: 068c0a29a8b7 +IP: 127.0.0.1 +IP: ::1 +IP: 192.168.147.3 +RemoteAddr: 192.168.147.2:56006 +GET / HTTP/1.1 +Host: whoami.localhost +User-Agent: curl/8.7.1 +Accept: */* +Accept-Encoding: gzip +X-Forwarded-For: 192.168.147.1 +X-Forwarded-Host: whoami.localhost +X-Forwarded-Port: 80 +X-Forwarded-Proto: http +X-Forwarded-Server: 9232cdd4fd6c +X-Real-Ip: 192.168.147.1 +``` + +You can also open [http://whoami.localhost](http://whoami.localhost) in a browser to test the application: + +![whoami application Screenshot](../assets/img/getting-started/whoami-localhost.png) + +If you navigate to the **HTTP Routers** section of the Traefik dashboard, you can see that the `whoami.localhost` route is managed by the Traefik Docker provider: + +![Traefik Dashboard HTTP Routers Section Screenshot](../assets/img/getting-started/docker-router.png) + +That's it! You've successfully deployed Traefik and configured routing in Docker. + +## Next Steps + +- [Configure TLS](../reference/routing-configuration/http/tls/overview.md) +- [Set up Middlewares](../reference/routing-configuration/http/middlewares/overview.md) +- [Enable Metrics](../reference/install-configuration/observability/metrics.md) +- [Learn more about Docker provider](../reference/install-configuration/providers/docker.md) + +{!traefik-for-business-applications.md!} diff --git a/docs/content/getting-started/index.md b/docs/content/getting-started/index.md new file mode 100644 index 000000000..e9c71dc90 --- /dev/null +++ b/docs/content/getting-started/index.md @@ -0,0 +1,25 @@ +--- +title: "Getting Started with Traefik" +description: "Quick start guides for deploying Traefik in Kubernetes and Docker environments" +--- + +# Getting Started with Traefik + +Traefik can be deployed in various environments. Choose your preferred deployment method: + +- [Kubernetes Quick Start](./kubernetes.md) - Deploy Traefik using Helm +- [Docker Quick Start](./docker.md) - Deploy Traefik using Docker + +Each guide will help you: + +- Install Traefik +- Expose the dashboard +- Deploy a sample application +- Configure basic routing + +## Before You Begin + +Make sure you have the necessary prerequisites for your chosen environment: + +- **Kubernetes**: A running Kubernetes cluster, Helm 3, and kubectl +- **Docker**: Docker and optionally Docker Compose diff --git a/docs/content/getting-started/kubernetes.md b/docs/content/getting-started/kubernetes.md new file mode 100644 index 000000000..2ff2382a7 --- /dev/null +++ b/docs/content/getting-started/kubernetes.md @@ -0,0 +1,331 @@ +--- +title: "Kubernetes and Traefik Quick Start" +description: "Deploy Traefik in Kubernetes using Helm and expose your first service" +slug: quick-start-with-kubernetes +--- + +# Getting Started with Kubernetes and Traefik + +Kubernetes is a first-class citizen in Traefik, offering native support for Kubernetes resources and the latest Kubernetes standards. +Whether you're using Traefik's [IngressRoute CRD](../reference/routing-configuration/kubernetes/crd/http/ingressroute.md), [Ingress](../reference/routing-configuration/kubernetes/ingress.md) or the [Kubernetes Gateway API](../reference/routing-configuration/kubernetes/gateway-api.md), +Traefik provides a seamless experience for managing your Kubernetes traffic. + +This guide shows you how to: + +- Create a Kubernetes cluster using k3d +- Install Traefik using Helm +- Expose the Traefik dashboard +- Deploy a sample application +- Configure basic routing with IngressRoute and Gateway API + +## Prerequisites + +- Kubernetes +- Helm 3 +- kubectl +- k3d (for local cluster creation) + +## Create a Kubernetes Cluster + +### Using k3d + +Create a cluster with the following command. This command: + +- Creates a k3d cluster named "traefik" +- Maps ports 80, 443, and 8000 to the loadbalancer for accessing services +- Disables the built-in Traefik ingress controller to avoid conflicts + +```bash +k3d cluster create traefik \ + --port 80:80@loadbalancer \ + --port 443:443@loadbalancer \ + --port 8000:8000@loadbalancer \ + --k3s-arg "--disable=traefik@server:0" +``` + +Configure kubectl: + +```bash +kubectl cluster-info --context k3d-traefik +``` + +## Install Traefik + +### Using Helm Values File + +Add the Traefik Helm repository: + +```bash +helm repo add traefik https://traefik.github.io/charts +helm repo update +``` + +Create a values file. This configuration: + +- Maps ports 80 and 443 to the web and websecure [entrypoints](../reference/install-configuration/entrypoints.md) +- Enables the [dashboard](../reference/install-configuration/api-dashboard.md) with a specific hostname rule +- Enables the [Kubernetes Gateway API provider](../reference/routing-configuration/kubernetes/gateway-api.md) +- Allows the Gateway to expose [HTTPRoutes](https://gateway-api.sigs.k8s.io/api-types/httproute/) from all namespaces + +```yaml +# values.yaml +ingressRoute: + dashboard: + enabled: true + matchRule: Host(`dashboard.localhost`) + entryPoints: + - web +providers: + kubernetesGateway: + enabled: true +gateway: + namespacePolicy: All +``` + +!!! info + The [KubernetesCRD](../reference/install-configuration/providers/kubernetes/kubernetes-crd.md) provider is enabled by default when using the Helm chart so we don't need to set it in the values file. + +Install Traefik: + +```bash +helm install traefik traefik/traefik -f values.yaml --wait +``` + +### Using Helm CLI Arguments + +Alternatively, you can install Traefik using CLI arguments. This command: + +- Maps ports `30000` and `30001` to the web and websecure entrypoints +- Enables the dashboard with a specific hostname rule +- Enables the [Kubernetes Gateway API provider](../reference/routing-configuration/kubernetes/gateway-api.md) +- Allows the Gateway to expose HTTPRoutes from all namespaces + +```bash +helm install traefik traefik/traefik --wait \ + --set ingressRoute.dashboard.enabled=true \ + --set ingressRoute.dashboard.matchRule='Host(`dashboard.localhost`)' \ + --set ingressRoute.dashboard.entryPoints={web} \ + --set providers.kubernetesGateway.enabled=true \ + --set gateway.namespacePolicy=All +``` + +!!! info + The [KubernetesCRD](../reference/install-configuration/providers/kubernetes/kubernetes-crd.md) provider is enabled by default when using the Helm chart so we don't need to set it in the CLI arguments. + +When Traefik is installed with the Gateway API provider enabled, it automatically creates a default GatewayClass named **traefik**: + +```bash +kubectl describe GatewayClass traefik +``` + +## Expose the Dashboard + +The dashboard is exposed with an [IngressRoute](../reference/routing-configuration/kubernetes/crd/http/ingressroute.md) provided by the Chart, as we defined in the helm values during installation. + +Access it at: + +[http://dashboard.localhost/dashboard/](http://dashboard.localhost/dashboard/) + +![Traefik Dashboard Screenshot](../assets/img/getting-started/traefik-dashboard.png) + +## Deploy a Sample Application + +Create a deployment: + +```yaml +# whoami.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: whoami +spec: + replicas: 2 + selector: + matchLabels: + app: whoami + template: + metadata: + labels: + app: whoami + spec: + containers: + - name: whoami + image: traefik/whoami + ports: + - containerPort: 80 +``` + +Create a service: + +```yaml +# whoami-service.yaml +apiVersion: v1 +kind: Service +metadata: + name: whoami +spec: + ports: + - port: 80 + selector: + app: whoami +``` + +Apply the manifests: + +```bash +kubectl apply -f whoami.yaml +kubectl apply -f whoami-service.yaml +``` + +## Exposing the Application Using an IngressRoute (CRD) + +Create an IngressRoute: + +```yaml +# whoami-ingressroute.yaml +apiVersion: traefik.io/v1alpha1 +kind: IngressRoute +metadata: + name: whoami +spec: + entryPoints: + - web + routes: + - match: Host(`whoami.localhost`) + kind: Rule + services: + - name: whoami + port: 80 +``` + +Apply the manifest: + +```bash +kubectl apply -f whoami-ingressroute.yaml +``` + +### Test Your Setup + +You can use the following curl command to verify that the application is correctly exposed: + +```bash +curl http://whoami.localhost + +Hostname: whoami-76c9859cfc-6v8hh +IP: 127.0.0.1 +IP: ::1 +IP: 10.42.0.11 +IP: fe80::20ad:eeff:fe44:a63 +RemoteAddr: 10.42.0.9:38280 +GET / HTTP/1.1 +Host: whoami.localhost +User-Agent: curl/8.7.1 +Accept: */* +Accept-Encoding: gzip +X-Forwarded-For: 127.0.0.1 +X-Forwarded-Host: whoami.localhost +X-Forwarded-Port: 80 +X-Forwarded-Proto: http +X-Forwarded-Server: traefik-598946cd7-zds59 +X-Real-Ip: 127.0.0.1 +``` + +You can also visit [http://whoami.localhost](http://whoami.localhost) in a browser to verify that the application is exposed correctly: + +![whoami application Screenshot](../assets/img/getting-started/whoami-localhost.png) + +## Exposing the Application Using the Gateway API + +Traefik supports the Kubernetes Gateway API specification, which provides a more standardized way to configure ingress in Kubernetes. +When we installed Traefik earlier, we enabled the Gateway API provider. +You can verify this in the providers section of the Traefik dashboard. + +![Providers Section Screenshot](../assets/img/getting-started/providers.png) + +To use the Gateway API: + +Install the Gateway API CRDs in your cluster: + +```bash +kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml +``` + +Create an HTTPRoute. This configuration: + +- Creates an HTTPRoute named "whoami" +- Attaches it to the default Gateway that Traefik created during installation +- Configures routing for the hostname "whoami-gatewayapi.localhost" +- Routes all traffic to the whoami service on port 80 + +```yaml +# httproute.yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: whoami +spec: + parentRefs: + - name: traefik-gateway + hostnames: + - "whoami-gatewayapi.localhost" + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: whoami + port: 80 +``` + +Apply the manifest: + +```bash +kubectl apply -f httproute.yaml +``` + +### Test Your Setup + +You can use the following curl command to verify that the application is correctly exposed: + +```bash +curl http://whoami-gatewayapi.localhost + +Hostname: whoami-76c9859cfc-6v8hh +IP: 127.0.0.1 +IP: ::1 +IP: 10.42.0.11 +IP: fe80::20ad:eeff:fe44:a63 +RemoteAddr: 10.42.0.9:38280 +GET / HTTP/1.1 +Host: whoami.localhost +User-Agent: curl/8.7.1 +Accept: */* +Accept-Encoding: gzip +X-Forwarded-For: 127.0.0.1 +X-Forwarded-Host: whoami.localhost +X-Forwarded-Port: 80 +X-Forwarded-Proto: http +X-Forwarded-Server: traefik-598946cd7-zds59 +X-Real-Ip: 127.0.0.1 +``` + +You can now visit [http://whoami.localhost](http://whoami.localhost) in your browser to verify that the application is exposed correctly: + +![whoami application Screenshot](../assets/img/getting-started/whoami-localhost.png) + +If you navigate to the **HTTP Routes** section of the traefik dashboard, you can see that the `whoami.localhost` route is managed by the Traefik Kubernetes Gateway API provider: + +![Traefik Dashboard HTTP Routes Section Screenshot](../assets/img/getting-started/kubernetes-gateway.png) + +That's it! You've successfully deployed Traefik and configured routing in a Kubernetes cluster. + +## Next Steps + +- [Configure TLS](../reference/routing-configuration/http/tls/overview.md) +- [Set up Middlewares](../reference/routing-configuration/http/middlewares/overview.md) +- [Enable Metrics](../reference/install-configuration/observability/metrics.md) +- [Learn more about Kubernetes CRD provider](../reference/install-configuration/providers/kubernetes/kubernetes-crd.md) +- [Learn more about Kubernetes Gateway API provider](../reference/install-configuration/providers/kubernetes/kubernetes-gateway.md) + +{!traefik-for-business-applications.md!} diff --git a/docs/content/getting-started/quick-start-with-kubernetes.md b/docs/content/getting-started/quick-start-with-kubernetes.md index a595fde55..7e0b6acca 100644 --- a/docs/content/getting-started/quick-start-with-kubernetes.md +++ b/docs/content/getting-started/quick-start-with-kubernetes.md @@ -3,342 +3,4 @@ title: "Traefik Getting Started With Kubernetes" description: "Get started with Traefik Proxy and Kubernetes." --- -# Quick Start - -A Use Case of Traefik Proxy and Kubernetes -{: .subtitle } - -This guide is an introduction to using Traefik Proxy in a Kubernetes environment. -The objective is to learn how to run an application behind a Traefik reverse proxy in Kubernetes. -It presents and explains the basic blocks required to start with Traefik such as Ingress Controller, Ingresses, Deployments, static, and dynamic configuration. - -## Permissions and Accesses - -Traefik uses the Kubernetes API to discover running services. - -To use the Kubernetes API, Traefik needs some permissions. -This [permission mechanism](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) is based on roles defined by the cluster administrator. -The role is then bound to an account used by an application, in this case, Traefik Proxy. - -The first step is to create the role. -The [`ClusterRole`](https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/cluster-role-v1/#ClusterRole) resource enumerates the resources and actions available for the role. -In a file called `00-role.yml`, put the following `ClusterRole`: - -```yaml tab="00-role.yml" -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: traefik-role - -rules: - - apiGroups: - - "" - resources: - - services - - secrets - - nodes - verbs: - - get - - list - - watch - - apiGroups: - - discovery.k8s.io - resources: - - endpointslices - verbs: - - list - - watch - - apiGroups: - - extensions - - networking.k8s.io - resources: - - ingresses - - ingressclasses - verbs: - - get - - list - - watch - - apiGroups: - - extensions - - networking.k8s.io - resources: - - ingresses/status - verbs: - - update - - apiGroups: - - traefik.io - resources: - - middlewares - - middlewaretcps - - ingressroutes - - traefikservices - - ingressroutetcps - - ingressrouteudps - - tlsoptions - - tlsstores - - serverstransports - - serverstransporttcps - verbs: - - get - - list - - watch -``` - -!!! info "You can find the reference for this file [there](../../reference/dynamic-configuration/kubernetes-crd/#rbac)." - -The next step is to create a dedicated service account for Traefik. -In a file called `00-account.yml`, put the following [`ServiceAccount`](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/service-account-v1/#ServiceAccount) resource: - -```yaml tab="00-account.yml" -apiVersion: v1 -kind: ServiceAccount -metadata: - name: traefik-account -``` - -And then, bind the role on the account to apply the permissions and rules on the latter. In a file called `01-role-binding.yml`, put the -following [`ClusterRoleBinding`](https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/cluster-role-binding-v1/#ClusterRoleBinding) resource: - -```yaml tab="01-role-binding.yml" -kind: ClusterRoleBinding -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: traefik-role-binding - -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: traefik-role -subjects: - - kind: ServiceAccount - name: traefik-account - namespace: default # This tutorial uses the "default" K8s namespace. -``` - -!!! info "`roleRef` is the Kubernetes reference to the role created in `00-role.yml`." - -!!! info "`subjects` is the list of accounts reference." - - In this guide, it only contains the account created in `00-account.yml` - -## Deployment and Exposition - -!!! info "This section can be managed with the help of the [Traefik Helm chart](../install-traefik/#use-the-helm-chart)." - -The [ingress controller](https://traefik.io/glossary/kubernetes-ingress-and-ingress-controller-101/#what-is-a-kubernetes-ingress-controller) -is a software that runs in the same way as any other application on a cluster. -To start Traefik on the Kubernetes cluster, -a [`Deployment`](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/) resource must exist to describe how to configure -and scale containers horizontally to support larger workloads. - -Start by creating a file called `02-traefik.yml` and paste the following `Deployment` resource: - -```yaml tab="02-traefik.yml" -kind: Deployment -apiVersion: apps/v1 -metadata: - name: traefik-deployment - labels: - app: traefik - -spec: - replicas: 1 - selector: - matchLabels: - app: traefik - template: - metadata: - labels: - app: traefik - spec: - serviceAccountName: traefik-account - containers: - - name: traefik - image: traefik:v3.4 - args: - - --api.insecure - - --providers.kubernetesingress - ports: - - name: web - containerPort: 80 - - name: dashboard - containerPort: 8080 -``` - -The deployment contains an important attribute for customizing Traefik: `args`. -These arguments are the static configuration for Traefik. -From here, it is possible to enable the dashboard, -configure entry points, -select dynamic configuration providers, -and [more](../reference/static-configuration/cli.md). - -In this deployment, -the static configuration enables the Traefik dashboard, -and uses Kubernetes native Ingress resources as router definitions to route incoming requests. - -!!! info "When there is no entry point in the static configuration" - - Traefik creates a default one called `web` using the port `80` routing HTTP requests. - -!!! info "When enabling the [`api.insecure`](../../operations/api/#insecure) mode, Traefik exposes the dashboard on the port `8080`." - -A deployment manages scaling and then can create lots of containers, called [Pods](https://kubernetes.io/docs/concepts/workloads/pods/). -Each Pod is configured following the `spec` field in the deployment. -Given that, a Deployment can run multiple Traefik Proxy Pods, -a piece is required to forward the traffic to any of the instance: -namely a [`Service`](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#Service). -Create a file called `02-traefik-services.yml` and insert the two `Service` resources: - -```yaml tab="02-traefik-services.yml" -apiVersion: v1 -kind: Service -metadata: - name: traefik-dashboard-service - -spec: - type: LoadBalancer - ports: - - port: 8080 - targetPort: dashboard - selector: - app: traefik ---- -apiVersion: v1 -kind: Service -metadata: - name: traefik-web-service - -spec: - type: LoadBalancer - ports: - - targetPort: web - port: 80 - selector: - app: traefik -``` - -!!! warning "It is possible to expose a service in different ways." - - Depending on your working environment and use case, the `spec.type` might change. - It is strongly recommended to understand the available [service types](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) before proceeding to the next step. - -It is now time to apply those files on your cluster to start Traefik. - -```shell -kubectl apply -f 00-role.yml \ - -f 00-account.yml \ - -f 01-role-binding.yml \ - -f 02-traefik.yml \ - -f 02-traefik-services.yml -``` - -## Proxying applications - -The only part still missing is the business application behind the reverse proxy. -For this guide, we use the example application [traefik/whoami](https://github.com/traefik/whoami), -but the principles are applicable to any other application. - -The `whoami` application is an HTTP server running on port 80 which answers host-related information to the incoming requests. -As usual, start by creating a file called `03-whoami.yml` and paste the following `Deployment` resource: - -```yaml tab="03-whoami.yml" -kind: Deployment -apiVersion: apps/v1 -metadata: - name: whoami - labels: - app: whoami - -spec: - replicas: 1 - selector: - matchLabels: - app: whoami - template: - metadata: - labels: - app: whoami - spec: - containers: - - name: whoami - image: traefik/whoami - ports: - - name: web - containerPort: 80 -``` - -And continue by creating the following `Service` resource in a file called `03-whoami-services.yml`: - -```yaml tab="03-whoami-services.yml" -apiVersion: v1 -kind: Service -metadata: - name: whoami - -spec: - ports: - - name: web - port: 80 - targetPort: web - - selector: - app: whoami -``` - -Thanks to the Kubernetes API, -Traefik is notified when an Ingress resource is created, updated, or deleted. -This makes the process dynamic. -The ingresses are, in a way, the [dynamic configuration](../../providers/kubernetes-ingress/) for Traefik. - -!!! tip - - Find more information on [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), - and [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) in the official Kubernetes documentation. - -Create a file called `04-whoami-ingress.yml` and insert the `Ingress` resource: - -```yaml tab="04-whoami-ingress.yml" -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: whoami-ingress -spec: - rules: - - http: - paths: - - path: / - pathType: Prefix - backend: - service: - name: whoami - port: - name: web -``` - -This `Ingress` configures Traefik to redirect any incoming requests starting with `/` to the `whoami:80` service. - -At this point, all the configurations are ready. -It is time to apply those new files: - -```shell -kubectl apply -f 03-whoami.yml \ - -f 03-whoami-services.yml \ - -f 04-whoami-ingress.yml -``` - -Now you should be able to access the `whoami` application and the Traefik dashboard. -Load the dashboard on a web browser: [`http://localhost:8080`](http://localhost:8080). - -And now access the `whoami` application: - -```shell -curl -v http://localhost/ -``` - -!!! question "Going further" - - - [Filter the ingresses](../providers/kubernetes-ingress.md#ingressclass) to use with [IngressClass](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class) - - Use [IngressRoute CRD](../providers/kubernetes-crd.md) - - Protect [ingresses with TLS](../routing/providers/kubernetes-ingress.md#enabling-tls-via-annotations) - -{!traefik-for-business-applications.md!} +--8<-- "content/getting-started/kubernetes.md" diff --git a/docs/content/getting-started/quick-start.md b/docs/content/getting-started/quick-start.md index 4553a534f..0c1e2312e 100644 --- a/docs/content/getting-started/quick-start.md +++ b/docs/content/getting-started/quick-start.md @@ -3,118 +3,4 @@ title: "Traefik Getting Started Quickly" description: "Get started with Traefik Proxy and Docker." --- -# Quick Start - -A Use Case Using Docker -{: .subtitle } - -![quickstart-diagram](../assets/img/quickstart-diagram.png) - -## Launch Traefik With the Docker Provider - -Create a `docker-compose.yml` file where you will define a `reverse-proxy` service that uses the official Traefik image: - -```yaml -services: - reverse-proxy: - # The official v3 Traefik docker image - image: traefik:v3.4 - # Enables the web UI and tells Traefik to listen to docker - command: --api.insecure=true --providers.docker - ports: - # The HTTP port - - "80:80" - # The Web UI (enabled by --api.insecure=true) - - "8080:8080" - volumes: - # So that Traefik can listen to the Docker events - - /var/run/docker.sock:/var/run/docker.sock -``` - -**That's it. Now you can launch Traefik!** - -Start your `reverse-proxy` with the following command: - -```shell -docker compose up -d reverse-proxy -``` - -You can open a browser and go to `http://localhost:8080/api/rawdata` to see Traefik's API rawdata (you'll go back there once you have launched a service in step 2). - -## Traefik Detects New Services and Creates the Route for You - -Now that you have a Traefik instance up and running, you will deploy new services. - -Edit your `docker-compose.yml` file and add the following at the end of your file. - -```yaml -services: - - ... - - whoami: - # A container that exposes an API to show its IP address - image: traefik/whoami - labels: - - "traefik.http.routers.whoami.rule=Host(`whoami.docker.localhost`)" -``` - -The above defines `whoami`: a web service that outputs information about the machine it is deployed on (its IP address, host, and others). - -Start the `whoami` service with the following command: - -```shell -docker compose up -d whoami -``` - -Browse `http://localhost:8080/api/rawdata` and see that Traefik has automatically detected the new container and updated its own configuration. - -When Traefik detects new services, it creates the corresponding routes, so you can call them ... _let's see!_ (Here, you're using curl) - -```shell -curl -H Host:whoami.docker.localhost http://127.0.0.1 -``` - -_Shows the following output:_ - -```yaml -Hostname: a656c8ddca6c -IP: 172.27.0.3 -#... -``` - -## More Instances? Traefik Load Balances Them - -Run more instances of your `whoami` service with the following command: - -```shell -docker compose up -d --scale whoami=2 -``` - -Browse to `http://localhost:8080/api/rawdata` and see that Traefik has automatically detected the new instance of the container. - -Finally, see that Traefik load-balances between the two instances of your service by running the following command twice: - -```shell -curl -H Host:whoami.docker.localhost http://127.0.0.1 -``` - -The output will show alternatively one of the following: - -```yaml -Hostname: a656c8ddca6c -IP: 172.27.0.3 -#... -``` - -```yaml -Hostname: s458f154e1f1 -IP: 172.27.0.4 -# ... -``` - -!!! question "Where to Go Next?" - - Now that you have a basic understanding of how Traefik can automatically create the routes to your services and load balance them, it is time to dive into [the user guides](../../user-guides/docker-compose/basic-example/ "Link to the user guides") and [the documentation](/ "Link to the docs landing page") and let Traefik work for you! - -{!traefik-for-business-applications.md!} +--8<-- "content/getting-started/docker.md" diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index d8d50cd10..4b753187e 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -66,13 +66,12 @@ markdown_extensions: nav: - 'What is Traefik': 'index.md' - 'Getting Started': - - 'Concepts' : 'getting-started/concepts.md' + - 'Overview': 'getting-started/index.md' - 'Quick Start': - - 'Docker': 'getting-started/quick-start.md' - - 'Kubernetes': 'getting-started/quick-start-with-kubernetes.md' + - 'Kubernetes': 'getting-started/kubernetes.md' + - 'Docker': 'getting-started/docker.md' - 'Configuration Introduction': 'getting-started/configuration-overview.md' - - 'Install Traefik': 'getting-started/install-traefik.md' - - 'Frequently Asked Questions': 'getting-started/faq.md' + - 'Frequently Asked Questions': 'getting-started/faq.md' - 'Configuration Discovery': - 'Overview': 'providers/overview.md' - 'Docker': 'providers/docker.md'