Alias replace -> apply and add deprecation notice to replace

[ghost]

As discussed here.

The idea is to rename the replace command to apply, to closer match kubectl and lower mental overhead.

I implemented an alias to the replace command and marked the replace command as deprecated in the CLI help and docs. I don't expect this PR to pass without any discussion, I'm just hoping this PR will speed up and focus the discussion.

(It also includes a bit of documentation that was in master but had not been generated, I don't quite understand how that got through CI.)

---

This change is 

[k8s-ci-robot]

Hi @WillemMali. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with @k8s-bot ok to test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here.

[ghost]

I've previously opened an issue for this (#2616), linking the two with this comment.

[chrislovecnm]

Comments about refactor

[chrislovecnm]

You can add an alias here for replace and then remove the replace code. There is no need to have duplicate code.

[ghost]

I've implemented your suggestion, does my current PR look better to you?

[chrislovecnm]

@k8s-bot ok to test

[justinsb]

Thanks for the PR - I'll put some comments on the issue

[captainkerk]

I think that the big difference between kubectl apply and kubectl replace is that apply will create the resource if it doesn't exist, whereas replace will just fail. See: kubernetes/kubernetes#1702

I agree that apply is better than replace, but they are different in this regard. I think just aliasing them will lead to more confusion.

[k8s-github-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: WillemMali
We suggest the following additional approver: justinsb

Assign the PR to them by writing /assign @justinsb in a comment when ready.

Associated issue: 2603

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these OWNERS Files:

• OWNERS

You can indicate your approval by writing /approve in a comment
You can cancel your approval by writing /approve cancel in a comment

[k8s-github-robot]

@WillemMali PR needs rebase

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

Prevent issues from auto-closing with an /lifecycle frozen comment.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten
/remove-lifecycle stale

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close