diff --git a/slides/intro-fullday.yml b/slides/intro-fullday.yml index c8f4df3f..7d78c850 100644 --- a/slides/intro-fullday.yml +++ b/slides/intro-fullday.yml @@ -47,6 +47,7 @@ content: #- containers/Network_Drivers.md - containers/Local_Development_Workflow.md - containers/Container_Network_Model.md + - shared/yaml.md - containers/Compose_For_Dev_Stacks.md - containers/Exercise_Composefile.md - diff --git a/slides/intro-selfpaced.yml b/slides/intro-selfpaced.yml index 12d001ce..d2f0b65c 100644 --- a/slides/intro-selfpaced.yml +++ b/slides/intro-selfpaced.yml @@ -52,6 +52,7 @@ content: - - containers/Local_Development_Workflow.md - containers/Windows_Containers.md - containers/Working_With_Volumes.md + - shared/yaml.md - containers/Compose_For_Dev_Stacks.md - containers/Exercise_Composefile.md - containers/Docker_Machine.md diff --git a/slides/intro-twodays.yml b/slides/intro-twodays.yml index 069f0dac..5391283b 100644 --- a/slides/intro-twodays.yml +++ b/slides/intro-twodays.yml @@ -55,6 +55,7 @@ content: - - containers/Local_Development_Workflow.md - containers/Working_With_Volumes.md + - shared/yaml.md - containers/Compose_For_Dev_Stacks.md - containers/Exercise_Composefile.md - diff --git a/slides/kube-fullday.yml b/slides/kube-fullday.yml index ecf6e325..5ac7e868 100644 --- a/slides/kube-fullday.yml +++ b/slides/kube-fullday.yml @@ -75,6 +75,7 @@ content: #- k8s/scalingdockercoins.md #- shared/hastyconclusions.md #- k8s/daemonset.md + #- shared/yaml.md #- k8s/authoring-yaml.md #- k8s/exercise-yaml.md #- k8s/localkubeconfig.md diff --git a/slides/kube-selfpaced.yml b/slides/kube-selfpaced.yml index 06c0d1f0..750b3801 100644 --- a/slides/kube-selfpaced.yml +++ b/slides/kube-selfpaced.yml @@ -67,6 +67,7 @@ content: - k8s/scalingdockercoins.md - shared/hastyconclusions.md - k8s/daemonset.md + - shared/yaml.md - k8s/authoring-yaml.md #- k8s/exercise-yaml.md - diff --git a/slides/kube-twodays.yml b/slides/kube-twodays.yml index 33aa0f2f..0afad680 100644 --- a/slides/kube-twodays.yml +++ b/slides/kube-twodays.yml @@ -66,6 +66,7 @@ content: - k8s/scalingdockercoins.md - shared/hastyconclusions.md - k8s/daemonset.md + - shared/yaml.md - k8s/authoring-yaml.md #- k8s/exercise-yaml.md - diff --git a/slides/shared/yaml.md b/slides/shared/yaml.md new file mode 100644 index 00000000..079dbefc --- /dev/null +++ b/slides/shared/yaml.md @@ -0,0 +1,310 @@ +# Gentle introduction to YAML + +- YAML Ain't Markup Language (according to [yaml.org][yaml]) + +- *Almost* required when working with containers: + + - Docker Compose files + + - Kubernetes manifests + + - Many CI pipelines (GitHub, GitLab...) + +- If you don't know much about YAML, this is for you! + +[yaml]: https://yaml.org/ + +--- + +## What is it? + +- Data representation language + +```yaml +- country: France + capital: Paris + code: fr + population: 68042591 +- country: Germany + capital: Berlin + code: de + population: 84270625 +- country: Norway + capital: Oslo + code: no # It's a trap! + population: 5425270 +``` + +- Even without knowing YAML, we probably can add a country to that file :) + +--- + +## Trying YAML + +- Method 1: in the browser + + https://onlineyamltools.com/convert-yaml-to-json + + https://onlineyamltools.com/highlight-yaml + +- Method 2: in a shell + + ```bash + yq . foo.yaml + ``` + +- Method 3: in Python + + ```python + import yaml; yaml.safe_load(""" + - country: France + capital: Paris + """) + ``` + +--- + +## Basic stuff + +- Strings, numbers, boolean values, `null` + +- Sequences (=arrays, lists) + +- Mappings (=objects) + +- Superset of JSON + + (if you know JSON, you can just write JSON) + +- Comments start with `#` + +--- + +## Sequences + +- Example: sequence of strings + ```yaml + [ "france", "germany", "norway" ] + ``` + +- Example: the same sequence, without the double-quotes + ```yaml + [ france, germany, norway ] + ``` + +- Example: the same sequence, in "block collection style" (=multi-line) + ```yaml + - france + - germany + - norway + ``` + +--- + +## Mappings + +- Example: mapping strings to numbers + ```yaml + { "france": 68042591, "germany": 84270625, "norway": 5425270 } + ``` + +- Example: the same mapping, without the double-quotes + ```yaml + { "france": 68042591, "germany": 84270625, "norway": 5425270 } + ``` + +- Example: the same mapping, in "block collection style" + ```yaml + france: 68042591 + germany: 84270625 + norway: 5425270 + ``` + +--- + +## Combining types + +- In a sequence (or mapping) we can have different types + + (including other sequences or mappings) + +- Example: + ```yaml + questions: [ name, quest, favorite color ] + answers: [ "Arthur, King of the Britons", Holy Grail, purple, 42 ] + ``` + +- Note that we need to quote "Arthur" because of the comma + +- Note that we don't have the same number of elements in questions and answers + +--- + +## More combinations + +- Example: + ```yaml + - service: nginx + ports: [ 80, 443 ] + - service: bind + ports: [ 53/tcp, 53/udp ] + - service: ssh + ports: 22 + ``` + +- Note that `ports` doesn't always have the same type + + (the code handling that data will probably have to be smart!) + +--- + +## ⚠️ Automatic booleans + +```yaml +codes: + france: fr + germany: de + norway: no +``` + +-- + +```json +{ + "codes": { + "france": "fr", + "germany": "de", + "norway": false + } +} +``` + +--- + +## ⚠️ Automatic booleans + +- `no` can become `false` + + (it depends on the YAML parser used) + +- It should be quoted instead: + + ```yaml + codes: + france: fr + germany: de + norway: "no" + ``` + +--- + +## ⚠️ Automatic floats + +```yaml +version: + libfoo: 1.10 + fooctl: 1.0 +``` + +-- + +```json +{ + "version": { + "libfoo": 1.1, + "fooctl": 1 + } +} +``` + +--- + +## ⚠️ Automatic floats + +- Trailing zeros disappear + +- These should also be quoted: + + ```yaml + version: + libfoo: "1.10" + fooctl: "1.0" + ``` + +--- + +## ⚠️ Automatic times + +```yaml +portmap: +- 80:80 +- 22:22 +``` + +-- + +```json +{ + "portmap": [ + "80:80", + 1342 + ] +} +``` + +--- + +## ⚠️ Automatic times + +- `22:22` becomes `1342` + +- Thats 22 minutes and 22 seconds = 1342 seconds + +- Again, it should be quoted + +--- + +class: extra-details + +## Advanced features + +Anchors let you "memorize" and re-use content: + +```yaml +debian: &debian + packages: deb + latest-stable: bullseye + +also-debian: *debian + +ubuntu: + <<: *debian + latest-stable: jammy +``` + +--- + +class: extra-details + +## YAML, good or evil? + +- Natural progression from XML to JSON to YAML + +- There are other data languages out there + + (e.g. HCL, domain-specific things crafted with Ruby, CUE...) + +- Compromises are made, for instance: + + - more user-friendly → more "magic" with side effects + + - more powerful → steeper learning curve + +- Love it or loathe it but it's a good idea to understand it! + +- Interesting tool if you appreciate YAML: https://carvel.dev/ytt/ + +??? + +:EN:- Understanding YAML and its gotchas +:FR:- Comprendre le YAML et ses subtilités