github.com/nginxinc/kubernetes-ingress@v1.12.5/docs-web/installation/building-ingress-controller-image.md (about)

     1  # Building the Ingress Controller Image
     2  
     3  This document explains how to build an Ingress Controller image. Note that for NGINX, we provide the image though [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). For NGINX Plus, you need to build the image.
     4  
     5  ## Prerequisites
     6  
     7  Before you can build the image, make sure that the following software is installed on your machine:
     8  * [Docker](https://www.docker.com/products/docker) v18.09+
     9  * [GNU Make](https://www.gnu.org/software/make/)
    10  * [git](https://git-scm.com/)
    11  * [OpenSSL](https://www.openssl.org/), optionally, if you would like to generate a self-signed certificate and a key for the default server.
    12  * For NGINX Plus, you must have the NGINX Plus license -- the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`).
    13  
    14  Although the Ingress Controller is written in golang, golang is not required, you have the option to build the Ingress Controller in a Docker container.
    15  
    16  ## Building the Image and Pushing It to the Private Registry
    17  
    18  We build the image using the make utility and the provided `Makefile`. Let’s create the Ingress Controller binary, build an image and push the image to the private registry.
    19  
    20  **Note**: If you have a local golang environment, you can remove `TARGET=container` from the `make` commands to speed up the build.
    21  
    22  1. Make sure to run the `docker login` command first to log in to the registry.
    23  
    24     If you’re using Google Container Registry, make sure you’re logged into the gcloud tool by running the `gcloud auth login` and `gcloud auth configure-docker` commands.
    25  
    26  1. Clone the Ingress Controller repo:
    27      ```
    28      $ git clone https://github.com/nginxinc/kubernetes-ingress/
    29      $ cd kubernetes-ingress
    30      $ git checkout v1.12.5
    31      ```
    32  
    33  1. Build the image:
    34      * For **NGINX**:
    35        ```
    36        $ make debian-image PREFIX=myregistry.example.com/nginx-ingress TARGET=container
    37        ```
    38        or if you wish to use alpine
    39        ```
    40        $ make alpine-image PREFIX=myregistry.example.com/nginx-ingress TARGET=container
    41        ```
    42        `myregistry.example.com/nginx-ingress` defines the repo in your private registry where the image will be pushed. Substitute that value with the repo in your private registry.
    43  
    44        As a result, the image **myregistry.example.com/nginx-ingress:1.12.5** is built. Note that the tag `1.12.5` comes from the `VERSION` variable, defined in the Makefile.
    45  
    46      * For **NGINX Plus**, first, make sure that the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) of your license are located in the root of the project:
    47        ```
    48        $ ls nginx-repo.*
    49        nginx-repo.crt  nginx-repo.key
    50        ```
    51        Then run:
    52        ```
    53        $ make debian-image-plus PREFIX=myregistry.example.com/nginx-plus-ingress TARGET=container
    54        ```
    55        `myregistry.example.com/nginx-plus-ingress` defines the repo in your private registry where the image will be pushed. Substitute that value with the repo in your private registry.
    56  
    57        As a result, the image **myregistry.example.com/nginx-plus-ingress:1.12.5** is built. Note that the tag `1.12.5` comes from the `VERSION` variable, defined in the Makefile.
    58  
    59        **Note**: In the event of a patch version of NGINX Plus being [released](/nginx/releases/), make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--no-cache"` to the `make` command.
    60  
    61  1. Push the image:
    62      ```
    63      $ make push PREFIX=myregistry.example.com/nginx-ingress
    64      ```
    65      Note: If you're using a different tag, append `TAG=your-tag` to the command above.
    66  
    67  Next you will find the details about available Makefile targets and variables.
    68  
    69  ### Makefile Targets
    70  
    71  You can see a list of all the targets by running `make` without any target or `make help`
    72  
    73  Below you can find some of the most useful targets in the **Makefile**:
    74  * **build**: creates the Ingress Controller binary using the local golang environment (ignored when `TARGET` is `container`).
    75  * **alpine-image**: for building an alpine-based image with NGINX.
    76  * **alpine-image-plus**: for building an alpine-based image with NGINX Plus.
    77  * **debian-image**: for building a debian-based image with NGINX.
    78  * **debian-image-plus**: for building a debian-based image with NGINX Plus.
    79  * **debian-image-nap-plus**: for building a debian-based image with NGINX Plus and the [appprotect](/nginx-app-protect/) module.
    80  * **debian-image-opentracing**: for building a debian-based image with NGINX, [opentracing](https://github.com/opentracing-contrib/nginx-opentracing) module and the [Jaeger](https://www.jaegertracing.io/) tracer.
    81  * **debian-image-opentracing-plus**: for building a debian-based image with NGINX Plus, [opentracing](https://github.com/opentracing-contrib/nginx-opentracing) module and the [Jaeger](https://www.jaegertracing.io/) tracer.
    82  * **openshift-image**: for building an ubi-based image with NGINX for [Openshift](https://www.openshift.com/) clusters.
    83  * **openshift-image-plus**: for building an ubi-based image with NGINX Plus for [Openshift](https://www.openshift.com/) clusters.
    84  * **openshift-image-nap-plus**: for building an ubi-based image with NGINX Plus and the [appprotect](/nginx-app-protect/) module for [Openshift](https://www.openshift.com/) clusters.
    85  Note: You need to store your RHEL organization and activation keys in a file named `rhel_license` in the project root. Example:
    86    ```bash
    87    RHEL_ORGANIZATION=1111111
    88    RHEL_ACTIVATION_KEY=your-key
    89    ```
    90  
    91  A few other useful targets:
    92  * **push**: pushes the image to the Docker registry specified in `PREFIX` and `TAG` variables.
    93  * **all**: executes test `test`, `lint`, `verify-codegen`, `update-crds` and `debian-image`. If one of the targets fails, the execution process stops, reporting an error.
    94  * **test**: runs unit tests.
    95  * **certificate-and-key**: The Ingress Controller requires a certificate and a key for the default HTTP/HTTPS server. You can reference them in a TLS Secret in a command-line argument to the Ingress Controller. As an alternative, you can add a file in the PEM format with your certificate and key to the image as `/etc/nginx/secrets/default`. Optionally, you can generate a self-signed certificate and a key using this target. Note that you must add the `ADD` instruction in the Dockerfile to copy the cert and the key to the image.
    96  
    97  ### Makefile Variables
    98  
    99  The **Makefile** contains the following main variables for you to customize (either by changing the Makefile or by overriding the variables in the make command):
   100  * **PREFIX** -- the name of the image. The default is `nginx/nginx-ingress`.
   101  * **VERSION** -- the current version of the Ingress Controller.
   102  * **TAG** -- the tag added to the image. It's set to the value of the `VERSION` variable by default.
   103  * **DOCKER_BUILD_OPTIONS** -- the [options](https://docs.docker.com/engine/reference/commandline/build/#options) for the `docker build` command. For example, `--pull`.
   104  * **TARGET** -- By default, the Ingress Controller is compiled locally using a `local` golang environment. If you want to compile the Ingress Controller using your local golang environment, make sure that the Ingress Controller repo is in your `$GOPATH`. To compile the Ingress Controller using the Docker [golang](https://hub.docker.com/_/golang/) container, specify `TARGET=container`.