Velero: [Epic] Documentation overhaul

[carlisia]

Issues to address:

1) When I recently setup a cluster I found myself reading instructions from 4 different pages:
https://github.com/heptio/ark/blob/master/docs/aws-config.md
https://github.com/heptio/ark/blob/master/docs/quickstart.md
https://github.com/heptio/ark/blob/master/docs/build-from-scratch.md
https://github.com/heptio/ark/blob/gh-pages/master/install-overview.md

I'd like to make it so there's a single, clear entry point for setting up Ark.

2) Where to add new docs to?
I think our docs are at a point where it's not intuitive as to where to add new documentation to. I'd like to have the documentation reorganized so that this question becomes a no brainer.

3) Match example files to releases
People are executing example files for the wrong release AND THEN finding the correct one. I would like to have this addressed.

[carlisia]

Related tickets that I'll groom as I work through this one:

https://github.com/heptio/ark/issues/648
https://github.com/heptio/ark/issues/952
https://github.com/heptio/ark/issues/931
https://github.com/heptio/ark/issues/867
https://github.com/heptio/ark/issues/856
https://github.com/heptio/ark/issues/819

[carlisia]

Todo: add a list of what Ark can and cannot backup.

[carlisia]

Tutorial ideas:

• restore from clusterA to clusterB

[akosveres]

Documentating the exposed prometheus metrics, would be great as well.

[saplla]

Also please document what Ark actually does backup. From the looks of our backups it's not backing up the K8s masters (and therefore etcd), only PVs, so isn't a complete solution.

[ncdc]

Ark backs up everything you can ‘kubectl get’ and it also takes PV
snapshots. If you’re not seeing it back up something that you expected,
please let us know and we’ll help troubleshoot your issue. Thanks!

On Thu, Nov 1, 2018 at 6:23 AM saplla [e-mail] wrote:

Also please document what Ark actually does backup. From the looks of
our backups it's not backing up the K8s masters (and therefore etcd), only
PVs, so isn't a complete solution.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/heptio/ark/issues/980#issuecomment-434997634, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAABYqIIsvr9jlJQxHLURU8fVhsSLQaRks5uqsu-gaJpZM4X1pgp
.

[saplla]

@ncdc Thanks for confirming that. It wasn't clear from the docs. We're using Kops so it appears we need to manually backup the EBS volumes backing our masters. It'd be helpful to highlight that in the AWS docs.

[ncdc]

@saplla thanks for the feedback. We'll see what we can come up with. Ark's position is as a tool to back up what is deployed into your cluster, along with any associated persistent data. We strongly encourage our users to have a strategy for automating the provisioning clusters, including backing up and restoring things such as the certificates and CAs used to secure the cluster components.

[Ilyes512]

Not sure if this is the right place, but I thought a new issue just for this would be overkill...

Just wanted to report that on this page: https://velero.io/docs/v1.1.0/about/
This image: https://velero.io/docs/v1.1.0/img/backup-process.png still mentions ark. (I believe this needs to be velero)

[carlisia]

Good catch! Please go ahead and open a new issue. We need to track down who did that diagram and change the original, or just do a new one.

[Ilyes512]

Created the issue at https://github.com/heptio/velero/issues/1876

[a-mccarthy]

@carlisia do you still feel like this issue is relevant? If there are changes you want to see in the docs, I think it may be worth closing this and opening a new issue. Many of the docs listed have changed

[carlisia]

@a-mccarthy sorry for the delayed response! Yes, I agree with you. We don't need this epic, just "documentation" labels on those still open issues. Closing.