openshift-evangelists/kbe

Kubernetes By Example

kbe's Issues

Question: Why not minikube?

I am just wondering why you chose minishift instead of minikube for this tutorial?

Just a curious question 😄

Content doesn't explain how to run commands inside the cluster

In both the pod and deployment documents, the simple example service is validated with cURL commands running "from inside the cluster", e.g.

Let’s verify that from within the cluster (using kubectl describe first to get the IP of one of the pods):

 [cluster] $ curl 172.17.0.3:9876/info
 {"host": "172.17.0.3:9876", "version": "0.9", "from": "172.17.0.1"}

but no explanation is given as to how exactly to do this.

(FWIW, I am running minishift locally, so if it's an obvious feature in hosted OpenShift some clarification may be all that's necessary.)

Customize UI theme (copy)

• add a copy button to the right of each bash example command

Should we display the yaml on the page

Hi @mhausenblas ,

I was wondering that displaying the yaml configuration on the page would help the user to easily view the configuration up front instead of clicking on that hyperlink and refer.

Check the following screenshot.

Also, it would help user to copy and create a yaml file and run it manually which will help user to understand better than kubectl create -f <remote url> approach.

Let me know what is your opinion on it.

BTW, I am working on #4 and found that I need to go to the URL to understand the configuration file properly. Though, kubectl create -f <remote-url> approach seems quite easy to go through with demo but it seems the configuration info fade way from mind as well.

resolve deprecation issues related to `kubectl run` in `pods` section

Pods are the new default result from kubectl run (as of version 1.xx.x). Update content to reflect the change

Example suited Kubernetes environment unclear

On the front page we should tell those examples below are expected to run on Kubernetes version 1.x.x recommended. To reduce the confusion when something goes wrong.

Update README for abbreviation of KBE

It seems little weird to me that through the entire repo I couldn't find the full form of kbe. I know it is easy to guess at least to me that KBE -> Kubernetes by Example which might not be case for every users.

PersistentVolumeClaim/PersistentVolume example

Thanks for making this, it's awesome. It says in the volumes section:

A special type of volume is PersistentVolume, which we will cover elsewhere.

I can't find that anywhere though, so I'm just raising an issue here with the enhancement request.

master to main

TODO:

• create a new branch of master named main
• update README instructions (filed issue instead, see: #55)
• change the default branch to main

expected impacts:

• shouldn't impact publishing to gh-pages
• anyone with outstanding changes will need to pull changes from main instead of master. This should be a minor inconvenience (since contributions are normally made via PRs + feature branch) See #55 for next steps if impacted

Pod description innacurate

The pod description says that containers in a pod share the mount namespace which is false. Containers have their own file systems. In order to see each other's directories they need to use a shared Volume with EmptyDir or other

Dou you consider adding multiple language support?

Your tutorials are so perfect! Firstly, thanks a lot! I want to translate this pages as Turkish, what can i do? Do you consider adding multiple language, so we can send PR for other languages than English. Otherwise, I have to register new domain and clone kubernetesbyexample.com in my native language. Then i will give a reference by the link.

simpleservice:0.5.0 doesn't work

When I try to run this image from Quay, I get an Error: ImagePullBackOff. I do not have the same problem with centos:7. More info:

Failed to pull image "quay.io/openshiftlabs/simpleservice:0.5.0": rpc error: code = Unknown desc = failed to pull and unpack image "quay.io/openshiftlabs/simpleservice:0.5.0": failed to resolve reference "quay.io/openshiftlabs/simpleservice:0.5.0": failed to do request: Head https://quay.io/v2/openshiftlabs/simpleservice/manifests/0.5.0: x509: certificate signed by unknown authority

test coverage v1 - local tests

See #52 for Epic details

v1: local content validation (BYO cluster credentials)

• find all markdown files, foreach file{
• parse and extract example commands
• parse example responses
• establish test cases to ensure commands do not fail or return an error when executed in order
• add test cases to compare example response output with actual response output, report any diffs

update code examples

• remove dollar sign from bash example commands
• identify all example commands as bash
• move all command output into a separate block marked with cat

Add content for Ingress, IngressController, Admission Controllers, CRDs and others

Add content for Ingress, IngressController, Admission Controllers, CRDs and other resource types that aren't currently covered.

www.kubernetesbyexample.com

www. domain ain't working.

Update the A records?

Manual download of oc binary for Minishift is not required.

We do not need to download the oc binary as Minishift downloads a copy of it and we can reuse it through minishift oc-env command. We should the the existing steps [1] as below.

1. Install [Minishift](https://docs.openshift.org/latest/minishift/getting-started/installing.html)
2. Run `minishift start`
3. Run `minishift oc-env` and do as suggested in the output of the command
4. Log in using oc login -u system:admin with password admin
5. Create a symlink from `oc` like so:  `ln -s `which oc` kubectl`

[1] https://github.com/openshift-evangelists/kbe/blob/master/content/page/diy.md

Inconsistent domain names for service discovery

Minishift and Kubernetes default to different namespaces, myproject and default respectively and that makes the service discovery chapter non-consistent across environments.

The command

kubectl exec jumpod -c shell -i -t -- ping thesvc.default.svc.cluster.local

will work on Kubernetes cluster, but not in OpenShift as default is restricted and in most installation including minishift the user will no be allowed to use the namespace.

In case the tutorials want to as well target on-lin service users, it should not rely on hard-coded name, as the namespace names has to be unique across users, it would only work for one user.

There are some possible ways how to solve this.

The content could be tweaked so that the user is well aware of the namespaces. But that would require creation of separate paths for Kubernetes and OpenShift, as they have different ways to create them.

Other way is to teach the user some way how to learn the namepace, (is there actually some simple command on kubectl level what would return the current namespace ?) e.g.

kubectl get pod jumpod -o jsonpath="{.metadata.namespace}"

and then let the user substitute the name in the command

kubectl exec jumpod -c shell -i -t -- getent hosts thesvc.$YOUR_NAMESPACE.svc.cluster.local

Another one is provide some command that would figure out the FQDN on the server at runtime, like this dirty hack

kubectl exec jumpod -c shell -i -t -- /bin/bash -c 'NAME=`cat /etc/resolv.conf | grep -o "search [^ ]*"`; NAME=($NAME); NAME=${NAME[1]}; getent hosts thesvc.$NAME'

`jumpod` is not working out of the box

I was following this tutorial : http://kubernetesbyexample.com/sd/ , yet I could not do the kubectl exec jumpod -i -t -- dig thesvc.default.svc.cluster.local command with success because the jumpod crashes...

Here is the output of kubectl logs jumpod :

Loaded plugins: fastestmirror, ovl


 One of the configured repositories failed (Unknown),
 and yum doesn't have enough cached data to continue. At this point the only
 safe thing yum can do is fail. There are a few ways to work "fix" this:

     1. Contact the upstream for the repository and get them to fix the problem.

     2. Reconfigure the baseurl/etc. for the repository, to point to a working
        upstream. This is most often useful if you are using a newer
        distribution release than is supported by the repository (and the
        packages for the previous distribution release still work).

     3. Run the command with the repository temporarily disabled
            yum --disablerepo=<repoid> ...

     4. Disable the repository permanently, so yum won't use it by default. Yum
        will then just ignore the repository until you permanently enable it
        again or use --enablerepo for temporary usage:

            yum-config-manager --disable <repoid>
        or
            subscription-manager repos --disable=<repoid>

     5. Configure the failing repository to be skipped, if it is unavailable.
        Note that yum will try to contact the repo. when it runs most commands,
        so will have to try and fail each time (and thus. yum will be be much
        slower). If it is a very temporary problem though, this is often a nice
        compromise:

            yum-config-manager --save --setopt=<repoid>.skip_if_unavailable=true

Cannot find a valid baseurl for repo: base/7/x86_64
Could not retrieve mirrorlist http://mirrorlist.centos.org/?release=7&arch=x86_64&repo=os&infra=container error was
14: curl#6 - "Could not resolve host: mirrorlist.centos.org; Unknown error"

Kube DNS example doesn't work as described using OpenShift Playground

"[OpenShift Playground] is the option we used for most of the examples on the site." But I'm unsure if the Playground comes with Kube DNS. (There may not be anything we can do, but I figure it doesn't hurt to capture here.)

Suggest to use busybox as the jumpod in the Service Discovery page

The busybox image contains a lot of useful tools for network diagnosis, and also this can be used for real development .
see
https://raw.githubusercontent.com/hintcnuie/kbe/main/specs/sd/jumpod-busybox.yaml

"nodes" page needs regenerated/fresh example output

update the example responses on the "Nodes" page

kubectl proxy in API server access

In the example, kubectl proxy command is used to proxy a local port to the kube-apiserver:
$ kubectl proxy --port=8080
This will work only if you have a config file recording the address of kube-apiserver, either at the default location ~/.kube/config, or provided by the --kubeconfig= parameter.
If none exists, kubectl proxy --port=8080 will create a loop, proxying itself to itself, and a kubectl command will cause a confusing too many open files error message.

No cleanup steps in some chapters

Hello openshift-evangelists/kbe maintainers,

First of all, thank you for such a great online resource. The examples are crisp, clear and easy to follow. Specially the fact that your tutorial doesn't have a yaml file in the tutorial itself, but linked to another page, makes following the tutorials even easier.

One small nitpick I noticed that from chapters StatefulSets, we have stopped including cleanup code at the end. Is this intentional? If not would you like to have a PR to include cleanup steps? I would be very happy to contribute.

http/https issue on http://kubernetesbyexample.com/

Hi there,

probably a misconfigured route (if running on OpenShift, which I assume):

Going to http://kubernetesbyexample.com/ opens KBE in all its beauty while using the https variant only shows the home link (the http version)...
Not really a huge issue, but since everyone is immediately suspicious these days about non-encrypted pages.... ;-)

Cheers!

Customize UI theme (hide `test` blocks)?

This UI update would allow hidden validation checks to be included throughout the content:

• hide all code blocks labeled with test

Or ... find another approach that will help enable test automation (without code duplication)

Next steps would involve automating the extraction of all example commands.

Then:

1. After extraction, each command that is labeled with bash or testshould be executed in order. Commands labeled with cat can be safely ignored
2. Print error responses and keep a count of the errors while running the tests
3. Display a summary of the error counts when the tests are complete

Food for though: Assume local git clone to shorten URLs in shell examples

The current examples grep the k8s resources straight from Github (https://raw.githubusercontent.com/mhausenblas/kbe/master/ ...). This makes it convenient since no other setup is required. At the same time it makes hard to understand which yaml is used. Which made me always scroll to the right.

Here is a simple example that assumes a local copy:

For me easier to read. At the same time I want the yamls open in my editor anyway to understand / check whats I am going to start next.

Hyperlink next and previous topic on current page for easy navigation

Currently, if I am in a particular page then I should have next or previous topic link at the bottom of the page. Otherwise, I need to click back and then select next topic in its current form.

typo in services.md

Was reading this: http://kubernetesbyexample.com/services/

And found a typo in the command:

$ kubectl gkubectl get pods -l app=sise

Notice the "gkubectl" - that shouldn't be there.

Looks like this is line 112 here: https://github.com/mhausenblas/kbe/blame/master/content/page/services.md#L112

Epic: test coverage for content pages

TODO:

v1: local content validation (BYO cluster credentials)

• find markdown files, foreach file{
• parse and extract example commands
• parse example responses
• establish test cases to ensure commands do not fail or return an error when executed in order
• add test cases to compare example response output with actual response output, report any diffs
• provide the date, time, and k8s API version that was most recently used to validate the content #26, #63

v2: test automation

• automated updates of example responses
• automated test coverage (nightly)
• report results of test runs
  • via GitHub repo
  • new /status page?

v3:

• include separate reports per k8s release (cover last three releases of K8s)?
• include separate reports for the two most recent releases of OpenShift?
• investigate opportunities to contribute to, or borrow examples from upstream k8s test coverage examples

Update the examples to Minishift version 1.0.0

We have now Minishift 1.0.0 released around 10 days ago.

Also, it uses the OpenShift version 1.5.0 which has Kubernetes 1.5.2.

Happy to look into it 😄

update mirror at quay.io/repository/openshiftlabs/jump

quay.io/mhausenblas/jump:0.2 should be mirrored on https://quay.io/organization/openshiftlabs:

• docker pull quay.io/mhausenblas/jump:0.2
• docker tag quay.io/mhausenblas/jump:0.2 quay.io/openshiftlabs/jump:0.2
• docker push quay.io/openshiftlabs/jump:0.2

Services page mentions iptables, but it's not easy to access

content/page/services.md - currently recommends using minikube ssh to access the VM environment.

Can we offer an exmaple that will work with Katacoda and other platforms as well?

customize UI theme

Customize the hugo theme, or switch to another solution that will make it easy to:

• style all output blocks (marked w/ cat) so that they hang below their associated bash example command

Content in the test branch will be ready to merge when these style update are complete

API spec reference for popular resources?

Consider parsing contents from the openAPI spec to generate markdown-based reference materials https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json

Would auto-generated content provide a better UX and improved SEO (compared to browsing the API using a swagger client)?

Consider adding basic example projects

This repo is really helpful. Nice & clean & to the point.

Have you considered expanding beyond command lists into some basic project setups? I'd love to see a project with 1-2 front ends talking to a back end with a few services & a database, sharing secrets, etc. Maybe a job that daily backs up the database file to a volume, keeping a week worth of backups. The actual project could be little more than "hello world" passed around, but understanding how to piece all of these components together from scratch would be great.

fatal: coudn't find remote ref master

Having trouble pulling updates from master? (fatal: coudn't find remote ref master)

Try the following to fix your remote/upstream references:

1. git pull origin
2. git checkout -b main
3. git branch main -u origin/main
4. git remote set-head origin main
5. git branch --set-upstream-to=origin/main main
6. git branch -d master
7. git branch -d -r origin/master

Then, open your repo's branch settings on GitHub and change the default branch to main at:

https://github.com/ <YOUR_GITHUB_USERNAME_HERE> /kbe/settings/branches

This should get you back to the usual workflow... Do this before adding new changes:

1. git pull # as usual, always run git pull before cutting your next feature branch
2. checkout -b my_new_feature_branch # to cut the new branch (cut from the fresh pull of origin/main)
3. commit, push, and send a PR when you're ready to share your changes #biz as usual

Congrats on completing this cleanup work!

new content: Admission Controller basics

Sub task of #37

New content:

• Admission Controllers

Later:

• Etcd
• CRDs

The Basics: how to get kubectl, kubeconfigs, export env vars

Add a general getting started section to help guide users from diy to pods.

This page should:

• provide clear information on how to connect to the cluster (kubeconfig) #41, #60
• provide clear information on how to download kubectl and how to add it to your $PATH
• establish a consistent namespace for running experiments #21
• work in coordination with #63 to help resolve: [#41, #21, #60, #26]

Also:

• Should provide information regarding the date, time, and k8s API version that was used to validate the content #26

Example commands should be portable

Found a few examples that could use an update. Examples should work given a stock Kubernetes cluster, and should not depend on oc or OpenShift:

• content/page/pods.md: examples use oc to fetch token. Use kubectl instead (or avoid tokens?)
• content/page/pods.md: replace export $OPENSHIFT_API w/ export $K8S_API
• content/page/pods.md: curl example assumes namespace == 'default'
• content/page/nodes.md: needs fresh example output (mentions minishift)
• content/page/services.md: Services page mentions iptables, but it's not easy to access (minikube ssh example)

See also: #41, #60, #26, #21
Related content page: #64

Next/Previous links is not present in published KBE website

Hi @mhausenblas ,

The PR for Previous/next is merged but it seems the website is not updated yet.

Scrub mhausenblas/* images and manifests

@mhausenblas