Rancher 2.0 Documentation Schedule

Rancher
1

Hi Folks!

Update: 6/27/18

Hi Rancher Community,

I wanted to provide an update on the doc schedule. Right now, we’ve moved back some of our dates listed below by a week or so. I’m splitting time between writing the documents promised below, while keeping up with work being done by the dev team around external authentication. If you have any questions about the schedule, feel free to ask below!

I’m Mark Bishop, the technical writer here at Rancher. After reading many of the threads on our forum, I know the Rancher community has concerns about the current lack of documentation around the 2.0 release. Your concerns are completely warranted–I know how frustrating a lack of documentation can be.

Starting today, I want to be more transparent about our documentation schedule: when you can expect updates, what topics will be covered in those updates, etc. Here’s what I have planned:

Doc Release Schedule

The end of this post includes a rough schedule of planned documentation updates and the topics that they’ll cover. My hope is that the community will chime in and help us prioritize which topics to cover first. I will post this schedule here in the forums as a sticky thread. These dates are subject to change, but we’ll keep you updated of any schedule changes.

Doc Release Notes

As I publish documentation updates, I’m going to publish release notes along with them. These notes will provide a high-level summary of the changes in each drop. This way you can stay on top of any documentation that you need to support your Rancher setup. Again, I’ll post these notes as a sticky thread here in the forums I’ll post these notes in the Rancher Docs GitHub Repo.

Community Interaction

Lastly, I’m going to spend more time in the Rancher forums and the Rancher Slack channels to monitor where the community needs more documentation. I understand how frustrating it can feel when the user community doesn’t receive the interaction it deserves. To that end, I’ll keep an eye out for trending issues, direct users to existing documentation, and post links to doc updates and release notes in our Slack channel.

Finally, an apology from me! In keeping my head down writing docs, I’ve done a disservice to you, our customers. Often, the lack of response is more frustrating than the problem itself. I apologize for the radio silence, and I look forward to working with you guys to improve our doc set :slight_smile:

Sincerely,

Mark Bishop
Technical Writer @ Rancher

Documentation Schedule

7/3:

  • Project Resources:

    How to add resources to a project in support of your workloads. Resources covered include:

    • Certificates
    • Configmaps
    • Sidecars, Ingress, and DNS Records
    • Secrets
    • Registries

  • Storage:

    How to add storage for your Rancher clusters, including storage from cloud services such as Amazon, Azure, etc.

7/6:

  • Alerts and Notifiers:

    How to configure Rancher to inform you when important events occur within your clusters.

  • Logging:

    How to enable logging for your clusters and projects.

  • Nodes:

    How to scale the number of nodes in your cluster up or down.

TBD

The Rancher community is requesting API docs! I’m going to investigate scope and come up with an estimate for these docs. I’ll post a date when I have more information :slight_smile:

7 Likes
3

Great - and I totally agree - lack of communication makes small problems look like monsters!

You wanted feedback on priorities and topics - how would you like to get those?

4

Thanks Mark, this update is very welcome.

REST API Documentation is important to me
As is audit logging

1 Like
5

For my part (you’ll probably have a different view from everyone… but hopefully there is a majority common ground), more important than what is listed in this post is more information on:

  • How Rancher modifies default K8s behavior.
  • More information to help us work out the appropriate deployment architecture of Rancher - HA or not - K8S cluster - number of etcd, controlplane, etc.
  • More data on Ingress and how we can customize it, or use Traefik or other K8S ingress available - for a on-prem deployment without cloud load balancer.
  • Rancher CLI documentation and API documentation so as to be able to build automation.
  • Audit logging and monitoring
  • Networking options (pros and cons, considerations)
  • Storage options for persistent data

All this to me is more important than how to use the UI - I find the UI self-explanatory enough and I don’t want to be using the UI much other than for visualizing so my heart goes toward more technical data than UX.

4 Likes
6

Hi @etlweather,

To address your comments from earlier, you can leave them here or in our Slack channel. Just be sure to mention @mark if you leave them in Slack.

Thanks for your input on your preference for API/CLI docs over Rancher UI! I have a feeling that’s what most of the community will want. We’ll update the schedule after we get some more community feedback.

1 Like
7

I can second this one - right now for instance, Rancher is automatically setting up network policies to segment workloads into projects, where pods can only communicate within their own project. From what I understand, this only happens with the Canal network provider, not Calico or Flannel. It’s really unclear how this is configured though, and I’ve taken to disabling as much of this as possible in the RKE config so that I can “own” the config and not hit unexpected configuration that’s impossible to Google for.

Right now the source of truth for what Rancher’s doing on top of k8s is the Rancher source code, which is less than ideal. Docs for all this would be awesome. I agree that as an advanced Kubernetes user who is trying to deliver Rancher/k8s to less-advanced users within my organization, I much more need to know about the internals than how the UI works.

Rancher is awesome, and I especially love automatically provisioning custom cluster nodes and the ability to see what’s going on inside the cluster via a GUI. It’s just unclear to me what all is happening under the hood after the cluster is provisioned that differs from stock k8s.

3 Likes
8

Agree with this.
Personally I only use the UI for the creation and monitoring of clusters on-premise. Setting up cluster/project logging is also intreresting from a UI point-of-view.

Deployment of applications workload is handled by automation outside Rancher using Helm.
Would be great if there were clear instructions on how to go from a newly created cluster in Rancher UI/API to be able to use Helm from the controlplane node / remote machine

1 Like
9

thanks @bjornmagnusson. Between this thread and some webinars put on by marketing, consensus seems to point toward API docs. I’ll work with my team to get this prioritized :slight_smile:

1 Like
10

It’s actually interesting - what drafted me to Rancher was the UI. I was new to containers, and was looking for an easy to use orchestration that wouldn’t be something I have to spend weeks learning. Did everything point and click in the early days and Rancher got me up and running in no time.

Then I graduated from the UI and started running my containerized applications still through Rancher, but using the API to run things. Even built a tool to facilitate this which many have contributed too and seems appreciated by a good number of people.

Now comes Rancher 2.0. I’m no longer a newbie looking for a tool that will hold my hands while I cross the street. I want to understand it, I want to use it to its maximum potential and I want to do everything through configuration files (read Infrastructure as Code) and APIs.

So I think you basically have two crowd to think with. Existing users (and maybe a few new ones) will want the hard code documents on the internals, API, and whatnot. And the new users will want “baby steps” documents (like I wanted in my earlier days), the simple stuff, getting started, etc. without needing to know the underlying technology.

1 Like
11

I also share @etlweather point of view and list

12

As someone with very little experience with orchestration, I’m very much in need of “How to …” docs to get me started with using Rancher if I’m to buy into it as a longer term way of managing clusters across providers.

For example, I’m particularly looking forward to the docs on storage scheduled for this coming week as that’s something I’ve never managed to get up and running without problems. Ideally guides for setting up replicated storage with Longhorn or StorageOS.

I’d also love a guide to setting up things like CockroachDB on Rancher, they seem like a match made in heaven.

13

Hi community,

There are some schedule for deep documentation into for architecture, components and other things?

Att

14

I found it! There is a ebook about how Rancher works, available on site. There was all information that I needed.

Thanks!

15

Hi Mark, just checking if you have an estimated date for release of API docs yet?

1 Like
16

Hi @slartibastfast, currently out goal is to have API documentation delivered at the end of August. We may move some of these goals around, so I’ll keep you updated if the date changes.

1 Like
17

I would enjoy any feedback on the documentation/stand-up scripts I’ve written, here https://github.com/BradJonesLLC/gke-rancher, for Rancher 2.0 and GKE.

1 Like