diff --git a/docs/design/secrets.md b/docs/design/secrets.md
index 119c673a106..5f8cb501845 100644
--- a/docs/design/secrets.md
+++ b/docs/design/secrets.md
@@ -389,12 +389,14 @@ To create a pod that uses an ssh key stored as a secret, we first need to create
 
 ```json
 {
-  "apiVersion": "v1beta2",
   "kind": "Secret",
-  "id": "ssh-key-secret",
+  "apiVersion": "v1beta3",
+  "metadata": {
+    "name": "ssh-key-secret"
+  },
   "data": {
-    "id-rsa.pub": "dmFsdWUtMQ0K",
-    "id-rsa": "dmFsdWUtMg0KDQo="
+    "id-rsa": "dmFsdWUtMg0KDQo=",
+    "id-rsa.pub": "dmFsdWUtMQ0K"
   }
 }
 ```
@@ -407,38 +409,36 @@ Now we can create a pod which references the secret with the ssh key and consume
 
 ```json
 {
-  "id": "secret-test-pod",
   "kind": "Pod",
-  "apiVersion":"v1beta2",
-  "labels": {
-    "name": "secret-test"
+  "apiVersion": "v1beta3",
+  "metadata": {
+    "name": "secret-test-pod",
+    "labels": {
+      "name": "secret-test"
+    }
   },
-  "desiredState": {
-    "manifest": {
-      "version": "v1beta1",
-      "id": "secret-test-pod",
-      "containers": [{
+  "spec": {
+    "volumes": [
+      {
+        "name": "secret-volume",
+        "secret": {
+          "secretName": "ssh-key-secret"
+        }
+      }
+    ],
+    "containers": [
+      {
         "name": "ssh-test-container",
         "image": "mySshImage",
-        "volumeMounts": [{
-          "name": "secret-volume",
-          "mountPath": "/etc/secret-volume",
-          "readOnly": true
-        }]
-      }],
-      "volumes": [{
-        "name": "secret-volume",
-        "source": {
-          "secret": {
-            "target": {
-              "kind": "Secret",
-              "namespace": "example",
-              "name": "ssh-key-secret"
-            }
+        "volumeMounts": [
+          {
+            "name": "secret-volume",
+            "readOnly": true,
+            "mountPath": "/etc/secret-volume"
           }
-        }
-      }]
-    }
+        ]
+      }
+    ]
   }
 }
 ```
@@ -452,105 +452,116 @@ The container is then free to use the secret data to establish an ssh connection
 
 ### Use-Case: Pods with pod / test credentials
 
-Let's compare examples where a pod consumes a secret containing prod credentials and another pod
-consumes a secret with test environment credentials.
+This example illustrates a pod which consumes a secret containing prod
+credentials and another pod which consumes a secret with test environment
+credentials.
 
 The secrets:
 
 ```json
-[{
-  "apiVersion": "v1beta2",
-  "kind": "Secret",
-  "id": "prod-db-secret",
-  "data": {
-    "username": "dmFsdWUtMQ0K",
-    "password": "dmFsdWUtMg0KDQo="
-  }
-},
 {
-  "apiVersion": "v1beta2",
-  "kind": "Secret",
-  "id": "test-db-secret",
-  "data": {
-    "username": "dmFsdWUtMQ0K",
-    "password": "dmFsdWUtMg0KDQo="
-  }
-}]
+  "apiVersion": "v1beta3",
+  "kind": "List",
+  "items":
+  [{
+    "kind": "Secret",
+    "apiVersion": "v1beta3",
+    "metadata": {
+      "name": "prod-db-secret"
+    },
+    "data": {
+      "password": "dmFsdWUtMg0KDQo=",
+      "username": "dmFsdWUtMQ0K"
+    }
+  },
+  {
+    "kind": "Secret",
+    "apiVersion": "v1beta3",
+    "metadata": {
+      "name": "test-db-secret"
+    },
+    "data": {
+      "password": "dmFsdWUtMg0KDQo=",
+      "username": "dmFsdWUtMQ0K"
+    }
+  }]
+}
 ```
 
 The pods:
 
 ```json
-[{
-  "id": "prod-db-client-pod",
-  "kind": "Pod",
-  "apiVersion":"v1beta2",
-  "labels": {
-    "name": "prod-db-client"
-  },
-  "desiredState": {
-    "manifest": {
-      "version": "v1beta1",
-      "id": "prod-db-pod",
-      "containers": [{
-        "name": "db-client-container",
-        "image": "myClientImage",
-        "volumeMounts": [{
-          "name": "secret-volume",
-          "mountPath": "/etc/secret-volume",
-          "readOnly": true
-        }]
-      }],
-      "volumes": [{
-        "name": "secret-volume",
-        "source": {
-          "secret": {
-            "target": {
-              "kind": "Secret",
-              "namespace": "example",
-              "name": "prod-db-secret"
-            }
-          }
-        }
-      }]
-    }
-  }
-},
 {
-  "id": "test-db-client-pod",
-  "kind": "Pod",
-  "apiVersion":"v1beta2",
-  "labels": {
-    "name": "test-db-client"
-  },
-  "desiredState": {
-    "manifest": {
-      "version": "v1beta1",
-      "id": "test-db-pod",
-      "containers": [{
-        "name": "db-client-container",
-        "image": "myClientImage",
-        "volumeMounts": [{
+  "apiVersion": "v1beta3",
+  "kind": "List",
+  "items":
+  [{
+    "kind": "Pod",
+    "apiVersion": "v1beta3",
+    "metadata": {
+      "name": "prod-db-client-pod",
+      "labels": {
+        "name": "prod-db-client"
+      }
+    },
+    "spec": {
+      "volumes": [
+        {
           "name": "secret-volume",
-          "mountPath": "/etc/secret-volume",
-          "readOnly": true
-        }]
-      }],
-      "volumes": [{
-        "name": "secret-volume",
-        "source": {
           "secret": {
-            "target": {
-              "kind": "Secret",
-              "namespace": "example",
-              "name": "test-db-secret"
-            }
+            "secretName": "prod-db-secret"
           }
         }
-      }]
+      ],
+      "containers": [
+        {
+          "name": "db-client-container",
+          "image": "myClientImage",
+          "volumeMounts": [
+            {
+              "name": "secret-volume",
+              "readOnly": true,
+              "mountPath": "/etc/secret-volume"
+            }
+          ]
+        }
+      ]
     }
-  }
-}]
+  },
+  {
+    "kind": "Pod",
+    "apiVersion": "v1beta3",
+    "metadata": {
+      "name": "test-db-client-pod",
+      "labels": {
+        "name": "test-db-client"
+      }
+    },
+    "spec": {
+      "volumes": [
+        {
+          "name": "secret-volume",
+          "secret": {
+            "secretName": "test-db-secret"
+          }
+        }
+      ],
+      "containers": [
+        {
+          "name": "db-client-container",
+          "image": "myClientImage",
+          "volumeMounts": [
+            {
+              "name": "secret-volume",
+              "readOnly": true,
+              "mountPath": "/etc/secret-volume"
+            }
+          ]
+        }
+      ]
+    }
+  }]
+}
 ```
 
 The specs for the two pods differ only in the value of the object referred to by the secret volume