sigs.k8s.io/external-dns@v0.14.1/docs/contributing/getting-started.md (about)

     1  # Quick Start
     2  
     3  - [Git](https://git-scm.com/downloads)
     4  - [Go 1.21+](https://golang.org/dl/)
     5  - [Go modules](https://github.com/golang/go/wiki/Modules)
     6  - [golangci-lint](https://github.com/golangci/golangci-lint)
     7  - [ko](https://ko.build/)
     8  - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl)
     9  
    10  Compile and run locally against a remote k8s cluster.
    11  ```shell
    12  git clone https://github.com/kubernetes-sigs/external-dns.git && cd external-dns
    13  make build
    14  # login to remote k8s cluster
    15  ./build/external-dns --source=service --provider=inmemory --once
    16  ```
    17  
    18  Run linting, unit tests, and coverage report.
    19  ```shell
    20  make lint
    21  make test
    22  make cover-html
    23  ```
    24  
    25  Build container image.
    26  ```shell
    27  make build.push IMAGE=your-registry/external-dns
    28  ```
    29  
    30  # Design
    31  
    32  ExternalDNS's sources of DNS records live in package [source](../../source). They implement the `Source` interface that has a single method `Endpoints` which returns the represented source's objects converted to `Endpoints`. Endpoints are just a tuple of DNS name and target where target can be an IP or another hostname.
    33  
    34  For example, the `ServiceSource` returns all Services converted to `Endpoints` where the hostname is the value of the `external-dns.alpha.kubernetes.io/hostname` annotation and the target is the IP of the load balancer or where the hostname is the value of the `external-dns.alpha.kubernetes.io/internal-hostname` annotation and the target is the IP of the service ClusterIP.
    35  
    36  This list of endpoints is passed to the [Plan](../../plan) which determines the difference between the current DNS records and the desired list of `Endpoints`.
    37  
    38  Once the difference has been figured out the list of intended changes is passed to a `Registry` which live in the [registry](../../registry) package. The registry is a wrapper and access point to DNS provider. Registry implements the ownership concept by marking owned records and filtering out records not owned by ExternalDNS before passing them to DNS provider.
    39  
    40  The [provider](../../provider) is the adapter to the DNS provider, e.g. Google Cloud DNS. It implements two methods: `ApplyChanges` to apply a set of changes filtered by `Registry` and `Records` to retrieve the current list of records from the DNS provider.
    41  
    42  The orchestration between the different components is controlled by the [controller](../../controller).
    43  
    44  You can pick which `Source` and `Provider` to use at runtime via the `--source` and `--provider` flags, respectively.
    45  
    46  # Adding a DNS Provider
    47  
    48  A typical way to start on, e.g. a CoreDNS provider, would be to add a `coredns.go` to the providers package and implement the interface methods. Then you would have to register your provider under a name in `main.go`, e.g. `coredns`, and would be able to trigger it's functions via setting `--provider=coredns`.
    49  
    50  Note, how your provider doesn't need to know anything about where the DNS records come from, nor does it have to figure out the difference between the current and the desired state, it merely executes the actions calculated by the plan.
    51  
    52  # Running GitHub Actions locally
    53  
    54  You can also extend the CI workflow which is currently implemented as GitHub Action within the [workflow](https://github.com/kubernetes-sigs/external-dns/tree/HEAD/.github/workflows) folder.
    55  In order to test your changes before committing you can leverage [act](https://github.com/nektos/act) to run the GitHub Action locally.
    56  
    57  Follow the installation instructions in the nektos/act [README.md](https://github.com/nektos/act/blob/master/README.md).
    58  Afterwards just run `act` within the root folder of the project.
    59  
    60  For further usage of `act` refer to its documentation.