Docs for using Ambassador as Ingress Controller

[inercia]

This PR documents how to install Ambassador as an Ingress Controller.

Ambassador is installed via the Ambassador Operator which is the recommended way of installing Ambassador (it makes sure users always have the latest version of Ambassador installed and takes care of updates as well).

[k8s-ci-robot]

Hi @inercia. Thanks for your PR.

I'm waiting for a kubernetes-sigs 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.

[aojea]

/ok-to-test
/lgtm
Thanks @inercia

[aojea]

/assign @BenTheElder

[aojea]

/hold
@inercia the current ingresses are adding some specific configuration to pin the ingress to the control plane node, so the port forwarding defined in the kind-config works.
Is this docs addressing it?

[amwat]

FYI: https://deploy-preview-1585--k8s-kind.netlify.app/docs/user/ingress/#ambassador

+1 to @aojea 's comment about ensuring the node-selector=ingress-ready part.

/hold
I tried to follow the basic instructions (single node) but the ingress didn't seem to work?
can you confirm whether or not it's compatible with the using ingress section.

[inercia]

Hi @aojea! Thanks for spending some time reviewing this. I didn't realize about the ingress-ready: "true" label. I have modified the code for adding a nodeSelector with that label, so it should happen automatically.

@amwat You are right, it was not working because I forgot to note that Ingress resources must include an annotation kubernetes.io/ingress.class: "ambassador" for being recognized by Ambassador. Otherwise, they will be ignored. I have updated the docs accordingly.

[aojea]

It's not working for me :(

Also, I think that for this section we should give more detailed steps, most users need more guidance on how to annotate the ingress resource

I forgot to note that Ingress resources must include an annotation kubernetes.io/ingress.class: "ambassador"

[amwat]

You will also need to add tolerations for node-role.kubernetes.io/master similar to that shown in the contour section.

Also, +1 to adding the annotation instruction explicitly as a step.
maybe in the using ingress section add a line, something like

If you are using Ambassador also run:
kubectl annotate ingress example-ingress kubernetes.io/ingress.class=ambassador

[inercia]

It's not working for me :(

What version of Kubernetes are you running? I have discovered it wasn't working with 1.18 (not completely sure the reason), but it should be working fine now. I have also added a kubectl wait in the instruction for being sure Ambassador is installed before going further. I would appreciate it if you could try the new code.

Also, I think that for this section we should give more detailed steps, most users need more guidance on how to annotate the ingress resource

Yes, in fact, Ingress Controllers should use the ingress.class annotation for differentiating who serves an Ingress, but most controllers assume that, if the annotation is not there, they should take over that Ingress (see Nginx and contour). Ambassador does the opposite (this behavior has not been standardized). I have added a note on how to add the annotation.

[aojea]

What version of Kubernetes are you running?

KIND is installing 1.18 by default now,

[inercia]

You will also need to add tolerations for node-role.kubernetes.io/master similar to that shown in the contour section.

@amwat I have added the toleration for running in masters. The new Ambassador deployment will have:

       tolerations:
       - effect: NoSchedule
         key: node-role.kubernetes.io/master
         operator: Equal

@aojea I have added a kubectl patch command for adding the annotation in the Ingress example. I have also added a kubectl wait for waiting for Ambassador to be ready, so it should be more reliable now...

[aojea]

KIND is installing 1.18 by default now,

no luck yet running the example with 1.18.2
pods are running, ingress patched but the curl to localhost/foo hangs :(

[concaf]

@aojea I just tried deploying Ambassador with Kind following the instructions and it seems to work for me.
I've tested this locally on Fedora 30, Kube 1.18, Docker 19.

I tried it again on a fresh VM on GCE (Ubuntu 16.04) with nothing installed except docker, kind and kubectl, and it works there as well. I have created a short screencast of the same for reference - https://asciinema.org/a/5ju0SBnNiP9s6NAhB6a0Sv4TT - PTAL.

[aojea]

@aojea I just tried deploying Ambassador with Kind following the instructions and it seems to work for me.
I've tested this locally on Fedora 30, Kube 1.18, Docker 19.

I tried it again on a fresh VM on GCE (Ubuntu 16.04) with nothing installed except docker, kind and kubectl, and it works there as well. I have created a short screencast of the same for reference - https://asciinema.org/a/5ju0SBnNiP9s6NAhB6a0Sv4TT - PTAL.

awesome, I think that my problem yesterday was that quay was down 🤔 .

quay.io/datawire/ambassador-operator:v1.2.3

Anyway, thanks for the detailed walkthrough, and sorry for being a bit picky, but it is in the best for everybody that things work out of the box, or that will cause a bad experience to users.

/lgtm

[inercia]

Apologies for the push -f: just removed some spurious blanks lines...

[aojea]

/lgtm
/hold cancel
👍

[amwat]

Thanks for adding this!
Tested locally and is working great for me.
/lgtm

[inercia]

/retest

[BenTheElder]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: BenTheElder, inercia

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

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [BenTheElder]

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

[aojea]

/lgtm

[inercia]

Thanks @aojea, @BenTheElder, @amwat, and @concaf for your patience and your time. :-)