Kubernetes manifests can be defined in json or yaml. The file extension .yaml, .yml, and .json can be used.
General Configuration Tips:
When defining configurations, specify the latest stable API version.
Configuration files should be stored in version control before being pushed to the cluster. This allows you to quickly roll back a configuration change if necessary. It also aids cluster re-creation and restoration.
Write your configuration files using YAML rather than JSON. Though these formats can be used interchangeably in almost all scenarios, YAML tends to be more user-friendly.
Group related objects into a single file whenever it makes sense. One file is often easier to manage than several. See the guestbook-all-in-one.yaml file as an example of this syntax.
Note also that many kubectl commands can be called on a directory. For example, you can call kubectl apply on a directory of config files.
Don’t specify default values unnecessarily: simple, minimal configuration will make errors less likely.
Put object descriptions in annotations, to allow better introspection
YAML vs JSON
YAML, which stands for Yet Another Markup Language, or YAML Ain’t Markup Language (depending who you ask) is a human-readable text-based format for specifying configuration-type information. For example, in this article, we’ll pick apart the YAML definitions for creating first a Pod, and then a Deployment.
Using YAML for K8s definitions gives you a number of advantages, including:
Convenience: You’ll no longer have to add all of your parameters to the command line
Maintenance: YAML files can be added to source control, so you can track changes
Flexibility: You’ll be able to create much more complex structures using YAML than you can on the command line
YAML is a superset of JSON, which means that any valid JSON file is also a valid YAML file.
Two types of structures in YAML are
YAML Maps
Lists Maps
YAML Maps
Maps let you associate name-value pairs, which of course is convenient when you’re trying to set up configuration information. For example, you might have a config file that starts like this:
---
apiVersion: v1
kind: Pod
The first line is a separator, and is optional unless you’re trying to define multiple structures in a single file. From there, as you can see, we have two values, v1 and Pod, mapped to two keys, apiVersion and kind.
This kind of thing is pretty simple, of course, and you can think of it in terms of its JSON equivalent:
{
"apiVersion": "v1",
"kind": "Pod"
}
Notice that in our YAML version, the quotation marks are optional; the processor can tell that you’re looking at a string based on the formatting.
You can also specify more complicated structures by creating a key that maps to another map, rather than a string, as in:
---
apiVersion: v1
kind: Pod
metadata:
name: nginxexample
labels:
app: web
In this case, we have a key, metadata, that has as its value a map with 2 more keys, name and labels. The labels key itself has a map as its value. You can nest these as far as you want to.
The YAML processor knows how all of these pieces relate to each other because we’ve indented the lines. In this example I’ve used 2 spaces for readability, but the number of spaces doesn’t matter — as long as it’s at least 1, and as long as you’re CONSISTENT. For example, name and labels are at the same indentation level, so the processor knows they’re both part of the same map; it knows that app is a value for labels because it’s indented further.
Quick note: NEVER use tabs in a YAML file.
So if we were to translate this to JSON, it would look like this:
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "nginxexample",
"labels": {
"app": "web"
}
}
}
YAML lists
YAML lists are literally a sequence of objects. For example:
args:
- sleep
- "1000"
- message
- "First Webserver"
As you can see here, you can have virtually any number of items in a list, which is defined as items that start with a dash (-) indented from the parent. So in JSON, this would be:
{
"args": ["sleep", "1000", "message", "First Webserver"]
}
And of course, members of the list can also be maps:
---
apiVersion: v1
kind: Pod
metadata:
name: nginxexample
labels:
app: web
spec:
containers:
- name: front-end
image: nginx
ports:
- containerPort: 80
So as you can see here, we have a list of containers “objects”, each of which consists of a name, an image, and a list of ports. Each list item under ports is itself a map that lists the containerPort and its value.
For completeness, let’s quickly look at the JSON equivalent:
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "nginxexample",
"labels": {
"app": "web"
}
},
"spec": {
"containers": [{
"name": "front-end",
"image": "nginx",
"ports": [{
"containerPort": "80"
}]
}
}
As you can see from above examples using YAML is much more easier than using JSON .
Using kubectl
• Use kubectl apply -f <directory>. This looks for Kubernetes configuration in all .yaml, .yml, and .json files in <directory> and passes it to apply.
• Use label selectors for get and delete operations instead of specific object names.
• Use kubectl run and kubectl expose to quickly create single-container Deployments and Services.