Add a FAQ #113
Add a FAQ #113
Conversation
|
Can one of the admins verify this patch? |
There was a problem hiding this comment.
@julia-stripe first off, thank you so much for the contribution! I've added a few comments. I'd also like @skriss and @abiogenesis-now to review too.
docs/faq.md
Outdated
|
|
||
| ## When is it appropriate to use Ark instead of etcd's built in backup/restore? | ||
|
|
||
| If you only want to backup/restore a single etcd cluster, you're probably better off using etcd's |
There was a problem hiding this comment.
I'd revise with something maybe like this (comments welcome!):
If you only want to backup/restore a single etcd cluster, you may be better of using etcd's backup and restore tooling. However, doing so will potentially restrict you to reconstructing your Kubernetes cluster data exactly as it was preserved, which may not be ideal (more on why below).
docs/faq.md
Outdated
|
|
||
| Ark is useful for: | ||
|
|
||
| * backing up etcd resources and persistent volume state |
There was a problem hiding this comment.
I'd replace "etcd" with "Kubernetes"
docs/faq.md
Outdated
| ## Will Ark restore my Kubernetes resources exactly the way they were before? | ||
|
|
||
| Yes, with some exceptions. For example, when Ark restores pods it deletes the `nodeName` from the | ||
| pod so that they can be scheduled onto a new node. You can see some more examples of the differences |
|
Oh, and once we settle on the final language, please make sure you sign your commit (https://github.com/heptio/ark/blob/master/CONTRIBUTING.md) |
julia-stripe
force-pushed
the
faq
branch
2 times, most recently
from
bff8382 to
b453d51
Compare
|
Made some updates! |
Signed-off-by: Julia Evans <julia@stripe.com>
docs/faq.md
Outdated
|
|
||
| ## When is it appropriate to use Ark instead of etcd's built in backup/restore? | ||
|
|
||
| If you only want to backup/restore a single etcd cluster, you may be better of using etcd's backup |
There was a problem hiding this comment.
nit: "...better of using..." -> "...better off using..."
docs/faq.md
Outdated
|
|
||
| ## When is it appropriate to use Ark instead of etcd's built in backup/restore? | ||
|
|
||
| If you only want to backup/restore a single etcd cluster, you may be better of using etcd's backup |
docs/faq.md
Outdated
|
|
||
| If you only want to backup/restore a single etcd cluster, you may be better of using etcd's backup | ||
| and restore tooling. However, doing so restricts you to reconstructing your Kubernetes cluster data | ||
| exactly as it was preserved. Etcd's restore tooling is good if what you want is to recover from |
There was a problem hiding this comment.
There's a little redundancy here, so I'd suggest rephrasing as:
Etcd's restore tooling is good for recovering from data loss in a single etcd cluster, but does not support more sophisticated restores.
Ark is useful in these scenarios, which include:
|
|
||
| ## Will Ark restore my Kubernetes resources exactly the way they were before? | ||
|
|
||
| Yes, with some exceptions. For example, when Ark restores pods it deletes the `nodeName` from the |
There was a problem hiding this comment.
@ncdc should we also mention the volume mount removal for the default service account token?
e.g. if we're mentioning "exceptions" we should be able to say something along the lines of:
The chief differences that Ark makes during a restore are:
- ...
- ...
So that readers can feel like they got most of what they needed to know without resorting to skimming the source code. (If we mention exceptions and only describe one, they may feel less comfortable).
There was a problem hiding this comment.
Also, I'm wondering if this particular answer should actually be documented in https://github.com/julia-stripe/ark/blob/bbef7a3e33f0d8d9ad5e948c09f557ec616bb11a/docs/concepts.md#3-restores, or if that is too deep in the docs that no one will see it.
There was a problem hiding this comment.
i'm going to leave this one to you all to resolve because I don't actually know what the chief differences with Ark are :)
There was a problem hiding this comment.
I think it is a good idea to document the behavior of each custom backup action and restorer. I don't think it needs to be in this PR. For now it's ok to link to the pod restorer source code. Longer term, that link should be replaced to point at the docs on the actions and restorers.
Signed-off-by: Julia Evans <julia@stripe.com>
|
|
||
| Etcd's restore tooling is good for recovering from data loss in a single etcd cluster, but does not | ||
| support more sophisticated restores. If you only want to recover from data loss in a single etcd | ||
| cluster, you're likely better off using etcd's backup/restore tooling. |
There was a problem hiding this comment.
I still prefer avoiding saying "likely" here. I don't have the best way to phrase this in my head yet, but basically if your goal is to backup and restore your cluster exactly as it was, then you're really treating your cluster as a pet, which can make recovery more difficult (the node names have to be the same because they're recorded in pod.spec.nodeName, for example). We feel that Ark is a better approach because it gives you the ability to throw away an unstable cluster and restore your Kube resources & data into a new cluster.
There was a problem hiding this comment.
feel free to change it however you think is best! =)
There was a problem hiding this comment.
it might be good to say
We feel that Ark is a better approach because it gives you the ability to throw away an unstable cluster and restore your Kube resources & data into a new cluster.
explicitly, that's an interesting perspective that I hadn't considered.
It's not totally clear to me in what cases you think using etcd's built in backup/restore methods is appropriate (never?)
There was a problem hiding this comment.
I think it'd be a good idea to back up etcd prior to upgrading etcd itself, for example.
I'm going to merge this and do a follow-up.
|
ok to test |
| * cluster migrations | ||
| * backing up a subset of your Kubernetes resources | ||
| * backing up Kubernetes resources that are stored across multiple etcd clusters (for example if you | ||
| run a custom apiserver) |
There was a problem hiding this comment.
I wonder if the following might be worthwhile adding to the list too: Ark is also a great option if you don't have access to etcd at all, such as with managed Kubernetes offerings. One example provider where that's the case is Google Container Engine.
(We actually run on GKE and picked Ark for this particular reason (and a few more)).
I had some questions about Ark that the documentation didn't answer. @ncdc very helpfully answered my questions in Slack so I am contributing them as documentation!
Feel totally free to reject/change this PR if you don't think it's helpful to other people, this is partly just an attempt on my part to make sure I've understood Ark properly.