diff --git a/docs/concepts-k8s.md b/docs/concepts-k8s.md
new file mode 100644
index 00000000..1ca3aa87
--- /dev/null
+++ b/docs/concepts-k8s.md
@@ -0,0 +1,203 @@
+# Kubernetes concepts
+
+- Kubernetes is a container management system
+
+- It runs and manages containerized applications on a cluster
+
+--
+
+- What does that really mean?
+
+---
+
+## Basic things we can ask Kubernetes to do
+
+--
+
+- Start 5 containers using image `atseashop/api:v1.3`
+
+--
+
+- Place an internal load balancer in front of these containers
+
+--
+
+- Start 10 containers using image `atseashop/webfront:v1.3`
+
+--
+
+- Place a public load balancer in front of these containers
+
+--
+
+- It's Black Friday (or Christmas), traffic spikes, grow our cluster and add containers
+
+--
+
+- New release! Replace my containers with the new image `atseashop/webfront:v1.4`
+
+--
+
+- Keep processing requests during the upgrade; update my containers one at a time
+
+---
+
+## Other things that Kubernetes can do for us
+
+- Basic autoscaling
+
+- Blue/green deployment, canary deployment
+
+- Long running services, but also batch (one-off) jobs
+
+- Overcommit our cluster and *evict* low-priority jobs
+
+- Run services with *stateful* data (databases etc.)
+
+- Fine-grained access control defining *what* can be done by *whom* on *which* resources
+
+- Integrating third party services (*service catalog*)
+
+- Automating complex tasks (*operators*)
+
+---
+
+## Kubernetes architecture
+
+---
+
+class: pic
+
+![haha only kidding](k8s-arch1.png)
+
+---
+
+## Kubernetes architecture
+
+- Ha ha ha ha
+
+- OK, I was trying to scare you, it's much simpler than that ❤️
+
+---
+
+class: pic
+
+![that one is more like the real thing](k8s-arch2.png)
+
+---
+
+## Credits
+
+- The first schema is a Kubernetes cluster with storage backed by multi-path iSCSI
+
+  (Courtesy of [Yongbok Kim](https://www.yongbok.net/blog/))
+
+- The second one is an good simplified representation of a Kubernetes cluster
+
+  (Courtesy of [Imesh Gunaratne](https://medium.com/containermind/a-reference-architecture-for-deploying-wso2-middleware-on-kubernetes-d4dee7601e8e))
+
+---
+
+## Kubernetes architecture: the master
+
+- The Kubernetes logic (its "brains") is a collection of services:
+
+  - the API server (our point of entry to everything!)
+  - core services like the scheduler and controller manager
+  - `etcd` (a highly available key/value store; the "database" of Kubernetes)
+
+- Together, these services form what is called the "master"
+
+- These services can run straight on a host, or in containers
+  <br/>
+  (that's an implementation detail)
+
+- `etcd` can be run on separate machines (first schema) or colocated (second schema)
+
+- We need at least one master, but we can have more (for high availability)
+
+---
+
+## Kubernetes architecture: the nodes
+
+- The nodes executing our containers run another collection of services:
+
+  - a container Engine (typically Docker)
+  - kubelet (the "node agent")
+  - kube-proxy (a necessary but not sufficient network component)
+
+- Nodes were formerly called "minions"
+
+- It is customary to *not* run apps on the node(s) running master components
+
+  (Except when using small development clusters) 
+
+---
+
+## Do we need to run Docker at all?
+
+No!
+
+--
+
+- By default, Kubernetes uses the Docker Engine to run containers
+
+- We could also use `rkt` ("Rocket") from CoreOS
+
+- Or leverage through the *Container Runtime Interface* other pluggable runtimes
+
+  (like CRI-O, or containerd)
+
+---
+
+## Do we need to run Docker at all?
+
+Yes!
+
+--
+
+- In this workshop, we will run our app on a single node first
+
+- We will need to build images and ship them around
+
+- You can do these things without Docker
+  <br/>
+  (and get diagnosed with NIH syndrome)
+
+- Docker is still the most stable container engine today
+  <br/>
+  (but other options are maturing very quickly)
+
+---
+
+## Do we need to run Docker at all?
+
+- On our development environments, CI pipelines ... :
+
+  *Yes, almost certainly*
+
+- On our production servers:
+
+  *Yes (today)*
+
+  *Probably not (in the future)*
+
+.footnote[More information about CRI [on the Kubernetes blog](http://blog.kubernetes.io/2016/12/]container-runtime-interface-cri-in-kubernetes.html).
+
+---
+
+## Kubernetes resources
+
+- The Kubernetes API defines a lot of objects called *resources*
+
+- These resources are organized by type, or `Kind` (in the API)
+
+- A few common resource types are:
+
+  - node (self-explanatory)
+  - pod (group of containers running together on a node)
+  - service (stable network endpoint to connect to one or multiple containers)
+  - namespace (more-or-less isolated group of things)
+  - secret (bundle of sensitive data to be passed to a container)
+ 
+  And much more; but let's start poking around!
diff --git a/docs/k8s-arch1.png b/docs/k8s-arch1.png
new file mode 100644
index 00000000..6dfa0930
Binary files /dev/null and b/docs/k8s-arch1.png differ
diff --git a/docs/k8s-arch2.png b/docs/k8s-arch2.png
new file mode 100644
index 00000000..6bb3847e
Binary files /dev/null and b/docs/k8s-arch2.png differ
diff --git a/docs/kube.yml b/docs/kube.yml
new file mode 100644
index 00000000..bee4b5db
--- /dev/null
+++ b/docs/kube.yml
@@ -0,0 +1,123 @@
+chapters:
+- |
+  class: title
+
+  .small[
+
+  Orchestrating microservices with Docker and Kubernetes
+
+  .small[.small[
+
+  **Be kind to the WiFi!**
+
+  *Use the 5G network*
+  <br/>
+  *Don't use your hotspot*
+  <br/>
+  *Don't stream videos from YouTube, Netflix, etc.
+  <br/>(if you're bored, watch local content instead)*
+
+  Thank you!
+
+  ]
+  ]
+  ]
+
+  ---
+
+  ## Intros
+ 
+  <!--
+  - Hello! We are
+    AJ ([@s0ulshake](https://twitter.com/s0ulshake))
+    &
+    Jérôme ([@jpetazzo](https://twitter.com/jpetazzo))
+  -->
+
+  - Hello! I am
+    Jérôme ([@jpetazzo](https://twitter.com/jpetazzo))
+
+  --
+
+  - This is our collective Docker knowledge:
+
+    ![Bell Curve](bell-curve.jpg)
+
+  ---
+
+  ## Agenda
+
+  .small[
+  - 09:00-09:10 Hello!
+  - 09:10-10:30 Part 1
+  - 10:30-11:00 coffee break
+  - 11:00-12:30 Part 2
+  - 12:30-13:30 lunch break
+  - 13:30-15:00 Part 3
+  - 15:00-15:30 coffee break
+  - 15:30-17:00 Part 4
+  - 17:00-18:00 Afterhours and Q&A
+  ]
+
+  <!--
+  - The tutorial will run from 9:00am to 12:20pm
+
+  - This will be fast-paced, but DON'T PANIC!
+
+  - There will be a coffee break at 10:30am
+    <br/>
+    (please remind me if I forget about it!)
+  -->
+
+  - All the content is publicly available (slides, code samples, scripts)
+
+    Upstream URL: https://github.com/jpetazzo/orchestration-workshop
+
+  - Feel free to interrupt for questions at any time
+
+  - Live feedback, questions, help on [Gitter](chat)
+
+    http://container.training/chat
+
+- intro.md
+- |
+  @@TOC@@
+- - prereqs-k8s.md
+  - versions-k8s.md
+  - sampleapp.md
+  - concepts-k8s.md
+  - kubectlget.md
+  - setup-k8s.md
+
+- - firstservice.md
+  - ourapponswarm.md
+  - updatingservices.md
+  - healthchecks.md
+- - operatingswarm.md
+  - netshoot.md
+  - ipsec.md
+  - swarmtools.md
+- - security.md
+  - secrets.md
+  - leastprivilege.md
+  - apiscope.md
+  - logging.md
+  - metrics.md
+  - stateful.md
+  - extratips.md
+  - end.md
+- |
+  class: title
+
+  That's all folks! <br/> Questions?
+
+  .small[.small[
+
+  Jérôme ([@jpetazzo](https://twitter.com/jpetazzo)) — [@docker](https://twitter.com/docker)
+
+  ]]
+
+  <!--
+  Tiffany ([@tiffanyfayj](https://twitter.com/tiffanyfayj))
+  AJ ([@s0ulshake](https://twitter.com/s0ulshake))
+  -->
diff --git a/docs/kubectlget.md b/docs/kubectlget.md
new file mode 100644
index 00000000..a422876d
--- /dev/null
+++ b/docs/kubectlget.md
@@ -0,0 +1,234 @@
+# First contact with `kubectl`
+
+- `kubectl` is (almost) the only tool we'll need to talk to Kubernetes
+
+- It is a rich CLI tool around the Kubernetes API
+
+  (Everything you can do with `kubectl`, you can do directly with the API)
+
+- On our machines, there is a `~/.kube/config` file with:
+
+  - the Kubernetes API address
+
+  - the path to our TLS certificates used to authenticate
+
+- You can also use the `--kubeconfig` flag to pass a config file
+
+- Or directly `--server`, `--user`, etc.
+
+- `kubectl` can be pronounced "Cube C T L", "Cube cuttle", "Cube cuddle"...
+
+---
+
+## `kubectl get`
+
+- Let's look at our `Node` resources with `kubectl get`!
+
+.exercise[
+
+- Look at the composition of our cluster:
+  ```bash
+  kubectl get node
+  ```
+
+- These commands are equivalent:
+  ```bash
+  kubectl get no
+  kubectl get node
+  kubectl get nodes
+  ```
+
+]
+
+---
+
+## From human-readable to machine-readable output
+
+- `kubectl get` can output JSON, YAML, or be directly formatted
+
+.exercise[
+
+- Give us more info about them nodes:
+  ```bash
+  kubectl get nodes -o wide
+  ```
+
+- Let's have some YAML:
+  ```bash
+  kubectl get no -o yaml
+  ```
+  See that `kind: List` at the end? It's the type of our result!
+
+]
+
+---
+
+## (Ab)using `kubectl` and `jq`
+
+- It's super easy to build custom reports
+
+.exercise[
+
+- Show the capacity of all our nodes as a stream of JSON objects:
+  ```bash
+    kubectl get nodes -o json | 
+            jq ".items[] | {name:.metadata.name} + .status.capacity"
+  ```
+
+]
+
+---
+
+## What's available?
+
+- `kubectl` has pretty good introspection facilities
+
+- We can list all available resource types by running `kubectl get`
+
+- We can view details about a resource with:
+  ```bash
+  kubectl describe type/name
+  kubectl describe type name
+  ```
+
+- We can view the definition for a resource type with:
+  ```bash
+  kubectl explain type
+  ```
+
+Each time, `type` can be singular, plural, or abbreviated type name.
+
+---
+
+## Services
+
+- A *service* is a stable endpoint to connect to "something"
+
+  (In the initial proposal, they were called "portals")
+
+.exercise[
+
+- List the services on our cluster with one of these commands:
+  ```bash
+  kubectl get services
+  kubectl get svc
+  ```
+
+]
+
+--
+
+There is already one service on our cluster: the Kubernetes API itself.
+
+---
+
+## ClusterIP services
+
+- A `ClusterIP` service is internal, available from the cluster only
+
+- This is useful for introspection from within containers
+
+.exercise[
+
+- Try to connect to the API:
+  ```bash
+  curl -k https://`10.96.0.1`
+  ```
+  
+  - `-k` is used to skip certificate verification
+  - Make sure to replace 10.96.0.1 with the CLUSTER-IP shown earlier
+
+]
+
+--
+
+The error that we see is expected: the Kubernetes API requires authentication.
+
+---
+
+## Listing running containers
+
+- Containers are manipulated through *pods*
+
+- A pod is a group of containers:
+
+ - running together (on the same node)
+
+ - sharing resources (RAM, CPU; but also network, volumes)
+
+.exercise[
+
+- List pods on our cluster:
+  ```bash
+  kubectl get pods
+  ```
+
+]
+
+--
+
+*These are not the pods you're looking for.* But where are they?!?
+
+---
+
+## Namespaces
+
+- Namespaces allow to segregate resources
+
+.exercise[
+
+- List the namespaces on our cluster with one of these commands:
+  ```bash
+  kubectl get namespaces
+  kubectl get namespace
+  kubectl get ns
+  ```
+
+]
+
+--
+
+*You know what ... This `kube-system` thing looks suspicious.*
+
+---
+
+## Accessing namespaces
+
+- By default, `kubectl` uses the `default` namespace
+
+- We can switch to a different namespace with the `-n` option
+
+.exercise[
+
+- List the pods in the `kube-system` namespace:
+  ```bash
+  kubectl -n kube-system get pods
+  ```
+
+]
+
+--
+
+*Ding ding ding ding ding!*
+
+---
+
+## What are all these pods?
+
+- `etcd` is our etcd server
+
+- `kube-apiserver` is the API server
+
+- `kube-controller-manager` and `kube-scheduler` are other master components
+
+- `kube-dns` is an additional component (not mandatory but super useful, so it's there)
+
+- `kube-proxy` is the (per-node) component managing port mappings and such
+
+- `weave` is the (per-node) component managing the network overlay
+
+- the `READY` column indicates the number of containers in each pod
+
+- the pods with a name ending with `-ip-172-31-XX-YY` are the master components
+  <br/>
+  (they have been specifically "pinned" to the master node)
diff --git a/docs/prereqs-k8s.md b/docs/prereqs-k8s.md
new file mode 100644
index 00000000..f7bdf393
--- /dev/null
+++ b/docs/prereqs-k8s.md
@@ -0,0 +1,172 @@
+# Pre-requirements
+
+- Computer with internet connection and a web browser
+
+- For instructor-led workshops: an SSH client to connect to remote machines
+
+  - on Linux, OS X, FreeBSD... you are probably all set
+
+  - on Windows, get [putty](http://www.putty.org/),
+  Microsoft [Win32 OpenSSH](https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH),
+  [Git BASH](https://git-for-windows.github.io/), or
+  [MobaXterm](http://mobaxterm.mobatek.net/)
+
+- For self-paced learning: SSH is not necessary if you use
+  [Play-With-Docker](http://www.play-with-docker.com/)
+
+- A tiny little bit of Docker knowledge
+
+  (that's totally OK if you're not a Docker expert!)
+
+---
+
+class: in-person, extra-details
+
+## Nice-to-haves
+
+- [Mosh](https://mosh.org/) instead of SSH, if your internet connection tends to lose packets
+  <br/>(available with `(apt|yum|brew) install mosh`; then connect with `mosh user@host`)
+
+- [GitHub](https://github.com/join) account
+  <br/>(if you want to fork the repo; also used to join Gitter)
+
+- [Gitter](https://gitter.im/) account
+  <br/>(to join the conversation during the workshop)
+
+- [Slack](https://community.docker.com/registrations/groups/4316) account
+  <br/>(to join the conversation after the workshop)
+
+- [Docker Hub](https://hub.docker.com) account
+  <br/>(it's one way to distribute images on your cluster)
+
+---
+
+class: extra-details
+
+## Extra details
+
+- This slide should have a little magnifying glass in the top right corner
+
+  (If it doesn't, it's because CSS is hard — Jérôme is only a backend person, alas)
+
+- Slides with that magnifying glass indicate slides providing extra details
+
+- Feel free to skip them if you're in a hurry!
+
+---
+
+## Hands-on sections
+
+- The whole workshop is hands-on
+
+- We will see Docker and Kubernetes in action
+
+- You are invited to reproduce all the demos
+
+- All hands-on sections are clearly identified, like the gray rectangle below
+
+.exercise[
+
+- This is the stuff you're supposed to do!
+- Go to [container.training](http://container.training/) to view these slides
+- Join the [chat room](chat)
+
+]
+
+---
+
+class: pic, in-person
+
+![You get five VMs](you-get-five-vms.jpg)
+
+---
+
+class: in-person
+
+## You get five VMs
+
+- Each person gets 5 private VMs (not shared with anybody else)
+- Kubernetes has been deployed and pre-configured on these machines
+- They'll remain up until the day after the tutorial
+- You should have a little card with login+password+IP addresses
+- You can automatically SSH from one VM to another
+
+.exercise[
+
+<!--
+```bash
+for N in $(seq 1 5); do
+  ssh -o StrictHostKeyChecking=no node$N true
+done
+for N in $(seq 1 5); do
+  (.
+  docker-machine rm -f node$N
+  ssh node$N "docker ps -aq | xargs -r docker rm -f"
+  ssh node$N sudo rm -f /etc/systemd/system/docker.service
+  ssh node$N sudo systemctl daemon-reload
+  echo Restarting node$N.
+  ssh node$N sudo systemctl restart docker
+  echo Restarted node$N.
+  ) &
+done
+wait
+```
+-->
+
+- Log into the first VM (`node1`) with SSH or MOSH
+- Check that you can SSH (without password) to `node2`:
+  ```bash
+  ssh node2
+  ```
+- Type `exit` or `^D` to come back to node1
+
+<!--
+```meta
+^D
+```
+-->
+
+]
+
+---
+
+## We will (mostly) interact with node1 only
+
+- Unless instructed, **all commands must be run from the first VM, `node1`**
+
+- We will only checkout/copy the code on `node1`
+
+- When we will use the other nodes, we will do it mostly through the Docker API
+
+- We will log into other nodes only for initial setup and a few "out of band" operations
+  <br/>(checking internal logs, debugging...)
+
+---
+
+## Terminals
+
+Once in a while, the instructions will say:
+<br/>"Open a new terminal."
+
+There are multiple ways to do this:
+
+- create a new window or tab on your machine, and SSH into the VM;
+
+- use screen or tmux on the VM and open a new window from there.
+
+You are welcome to use the method that you feel the most comfortable with.
+
+---
+
+## Tmux cheatsheet
+
+- Ctrl-b c → creates a new window
+- Ctrl-b n → go to next window
+- Ctrl-b p → go to previous window
+- Ctrl-b " → split window top/bottom
+- Ctrl-b % → split window left/right
+- Ctrl-b Alt-1 → rearrange windows in columns
+- Ctrl-b Alt-2 → rearrange windows in rows
+- Ctrl-b arrows → navigate to other windows
+- Ctrl-b d → detach session
+- tmux attach → reattach to session
diff --git a/docs/prereqs.md b/docs/prereqs.md
index fcadbefb..7af006ee 100644
--- a/docs/prereqs.md
+++ b/docs/prereqs.md
@@ -37,7 +37,7 @@ class: in-person, extra-details
   <br/>(to join the conversation after the workshop)
 
 - [Docker Hub](https://hub.docker.com) account
-  <br/>(it's one way to distribute images on your Swarm cluster)
+  <br/>(it's one way to distribute images on your cluster)
 
 ---
 
diff --git a/docs/versions-k8s.md b/docs/versions-k8s.md
new file mode 100644
index 00000000..795248b6
--- /dev/null
+++ b/docs/versions-k8s.md
@@ -0,0 +1,41 @@
+## Brand new versions!
+
+- Kubernetes 1.8
+- Docker Engine 17.10
+- Docker Compose 1.16
+
+
+.exercise[
+
+- Check all installed versions:
+  ```bash
+  kubectl version
+  docker version
+  docker-compose -v
+  ```
+
+]
+
+---
+
+class: extra-details
+
+## Kubernetes and Docker compatibility
+
+- Kubernetes only validates Docker Engine versions 1.11.2, 1.12.6, 1.13.1, and 17.03.2
+
+--
+
+class: extra-details
+
+- Are we living dangerously?
+
+--
+
+class: extra-details
+
+- "Validates" = continuous integration builds
+
+- The Docker API is versioned, and offers strong backward-compatibility
+
+  (If a client uses e.g. API v1.25, the Docker Engine will keep behaving the same way)