docs for migration of ingress resources in K8s v1.22 and beyond

[longwuyuan]

What this PR does / why we need it:

Placeholder for the docs needed as per #7397, for the builds of controller version 1.0.0.
This is Work-In-Progress

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Which issue/s this PR fixes

7397 (don;t change this)

How Has This Been Tested?

TODO

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I've read the CONTRIBUTION guide
• I have added tests to cover my changes.
• All new and existing tests passed.

[k8s-ci-robot]

@longwuyuan: This issue is currently awaiting triage.

If Ingress contributors determines this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

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.

[k8s-ci-robot]

Hi @longwuyuan. 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 /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.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: longwuyuan
To complete the pull request process, please assign thockin after the PR has been reviewed.
You can assign the PR to them by writing /assign @thockin in a comment when ready.

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

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[rikatz]

@longwuyuan thanks

Some examples:

I only have one Ingress Controller in my cluster, what can I do?

In this case, you need to make your Controller aware of the objects. If you have too many Ingress objects and they don't have yet the ingressClassName attribute or the ingress annotation (put the annotation here, can't remember it!) you should start your controller with the option --watch-ingress-without-class=true" or configure your helm chart values with .controller.watchIngressWithoutClass: true` (we need to fix this in the helm chart, if someone wants to make a PR ) https://github.com/kubernetes/ingress-nginx/blob/dev-v1/charts/ingress-nginx/templates/controller-deployment.yaml#L79

We highly recommend anyway to create the ingressClass as the following:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  labels:
    app.kubernetes.io/component: controller
  name: nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: k8s.io/ingress-nginx

And add the value "spec.ingressClassName=nginx" in your Ingress objects

I have more than one controller in my cluster and already use the annotation

No problem. This should still keep working, but we highly recommend you to test!

I have more than one controller running in my cluster, and want to use the new spec

So you need to create multiple Ingress Classes (see example one). But be aware that ingressClass works on a different way: you will need to change the .spec.controller value in your IngressClass and point the controller to the correct ingress class. Let's see some example, supposing that you have two Ingress Classes:

• nginx1 with .spec.controller equals to "k8s.io/ingress-nginx"
• nginx2 with .spec.controller equals to "k8s.io/ingress-nginx2"

When deploying your ingress controllers, you will have to change their --controller-class as following:

• controller-nginx1 with "k8s.io/ingress-nginx"
• controller-nginx2 with "k8s.io/ingress-nginx2"

So, when you create an Ingress Object with ingressClassName = nginx2, it will look for controllers with "controller-class=k8s.io/ingress-nginx2" and as controller-nginx2 is watching objects that points to ingressClass="k8s.io/ingress-nginx2" it will serve that object, while controller-nginx1 will ignore it

Bare in mind that if your controller-nginx2 is started with "--watch-ingress-without-class=true" it will serve objects without ingress-class, objects with the annotation configured in flag "--ingress-class" and same class value, and also objects pointing to the ingressClass that have the same .spec.controller as configured in --controller-class

[longwuyuan]

I suspect truncated but will fix formatting before merge.

On 13/08/21 11:54 pm, Johan Fleury wrote: ***@***.**** commented on this pull request. ------------------------------------------------------------------------ In docs/index.md <#7441 (comment)>: > +that are relevant to networking: + +- the `networking.k8s.io/v1beta1` API version of [IngressClass](/docs/concepts/services-networking/ingress/#ingre +- all beta versions of [Ingress](/docs/concepts/services-networking/ingress/): `extensions/v1beta1` and `networki + +On a v1.22 Kubernetes cluster, you'll be able to access Ingress and IngressClass +objects through the stable (v1) APIs, but access via their beta APIs won't be possible. +This change has been in +in discussion since +[2017](kubernetes/kubernetes#43214), +[2019](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/) with +1.16 Kubernetes API deprecations, and most recently in +KEP-1453: +[Graduate Ingress API to GA](https://github.com/kubernetes/enhancements/tree/master/keps/sig-network/1453-ingress + +Because of this deprecation of older api versions, the current code-base & release of the Ingress-Nginx-Controlle Is GH messing up or are these lines trucated? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#7441 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABGZVWUADDX5GZ22C7EBBNDT4VPMDANCNFSM5BTOSB5A>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>.

-- Thanks, ; Long

[longwuyuan]

Closing this one and will reopen a new one so I can PR into the dev-v1 branch and also make the review simpler