|
| 1 | +--- |
| 2 | +title: Deploy a New App |
| 3 | +--- |
| 4 | + |
| 5 | +## Introduction |
| 6 | + |
| 7 | +We use k8s to deploy our applications. |
| 8 | +You can choose, based on your needs, to use basic k8s manifests, [Kustomize](https://kustomize.io/) or [Helm Charts](https://helm.sh/docs/topics/charts/). |
| 9 | + |
| 10 | +If you have access to PoliNetwork's k8s cluster (you can perform `kubectl` commands) you can directly deploy from your machine. |
| 11 | +Although, this is not recommended in a production environment. |
| 12 | +Check [minikube](https://minikube.sigs.k8s.io/docs/start/?arch=%2Flinux%2Fx86-64%2Fstable%2Fbinary+download) to install a k8s cluster in your machine for testing purposes. |
| 13 | + |
| 14 | +:::note CD |
| 15 | +To deploy our applications, we use [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) |
| 16 | +with a [Git File Generator](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators-Git/#git-generator-files) |
| 17 | +pointing to the [polinetwork-cd](https://github.com/PoliNetworkOrg/polinetwork-cd/) GitHub repo. |
| 18 | + |
| 19 | +For more info, check out *[Getting Started / Basic Knowledge]* |
| 20 | +::: |
| 21 | + |
| 22 | +## Procedure |
| 23 | + |
| 24 | +1. Deploy a [Docker image](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/) |
| 25 | +2. [Create the app structure](#create-the-app-structure) |
| 26 | +3. Open a PR into polinetwork-cd |
| 27 | +4. Monitor deploy on ArgoCD |
| 28 | + |
| 29 | +### Create the app structure |
| 30 | +This is the crucial part, so make sure to follow it step-by-step. |
| 31 | +1. Clone [polinetwork-cd](https://github.com/PoliNetworkOrg/polinetwork-cd) repo |
| 32 | +2. Create a new branch (named as you like, e.g. `mc-server-deploy`) |
| 33 | +3. Create this minimal file structure: |
| 34 | +``` |
| 35 | +🗀 <k8s-namespace> |
| 36 | +├─ 🗀 src |
| 37 | +│ └── deployment.yaml |
| 38 | +│ |
| 39 | +└─ config.json |
| 40 | +``` |
| 41 | + |
| 42 | +:::info |
| 43 | +The `<k8s-namespace>` should be a slug (lowercase words separated by hyphens) identifier of the application/service you want to deploy. |
| 44 | +You can append, if necessary, an enviornment tag (e.g. `app-dev`, `app-prod`). |
| 45 | + |
| 46 | +Make sure that you use the same `<k8s-namespace>` value for both: |
| 47 | +- folder name |
| 48 | +- namespace field in k8s resources |
| 49 | +::: |
| 50 | + |
| 51 | +Inside `src/` you can put one of the following: |
| 52 | +- base k8s manifest ([example](https://raw.githubusercontent.com/kubernetes/website/main/content/en/examples/controllers/nginx-deployment.yaml)) |
| 53 | +- [Kustomize](https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/) |
| 54 | +- [Helm Chart](https://helm.sh/docs/topics/charts/) |
| 55 | + |
| 56 | +How these build tools are detected and distinguished is described [here](https://argo-cd.readthedocs.io/en/stable/user-guide/tool_detection/#tool-detection). |
| 57 | + |
| 58 | +:::important |
| 59 | +If you would like to use the Docker Image Auto-Updater, base k8s manifests are not supported, you must choose between Kustomize and Helm Chart. |
| 60 | + |
| 61 | +For more info, check the [relative section](#docker-image-auto-updater). |
| 62 | +::: |
| 63 | + |
| 64 | +## Docker Image Auto-Updater |
| 65 | +We use [ArgoCD Image Updater](https://argocd-image-updater.readthedocs.io/en/stable/) to |
| 66 | +automatically update docker images in deployments. |
| 67 | +This is an optional feature, but the alternative is to use a docker image fixed version (e.g. `nginx:1.27.4`). |
| 68 | + |
| 69 | +We use the `digest` strategy by default (also the only one we documented so far). |
| 70 | +Check out [the other strategies available](https://argocd-image-updater.readthedocs.io/en/stable/basics/update-strategies/). |
| 71 | + |
| 72 | +As mentioned in the [section above](#create-the-app-structure), you must use Kustomize or Helm Charts. |
| 73 | + |
| 74 | +:::warning |
| 75 | +Consider the following manifest: |
| 76 | +```yaml |
| 77 | +kind: Pod |
| 78 | +apiVersion: v1 |
| 79 | +metadata: |
| 80 | + name: example-pod |
| 81 | + namespace: test |
| 82 | +spec: |
| 83 | + containers: |
| 84 | + - name: nginx |
| 85 | + image: nginx:latest |
| 86 | +``` |
| 87 | +the image would **not update** if you **don't follow** this guide, even though there is `latest`. |
| 88 | +::: |
| 89 | + |
| 90 | +### Digest with Kustomize |
| 91 | +- [Full example](https://github.com/PoliNetworkOrg/polinetwork-cd/tree/main/tests/docker-test) |
| 92 | + |
| 93 | +In this configuration, we are using a Kustomize deployment with `digest` strategy. |
| 94 | +These are the steps to follow: (we are using `toto04/testcontainer` as the docker image) |
| 95 | + |
| 96 | +1. Create a `src/kustomization.yaml` with this content: |
| 97 | +```yaml |
| 98 | +apiVersion: kustomize.config.k8s.io/v1beta1 |
| 99 | +kind: Kustomization |
| 100 | +
|
| 101 | +resources: |
| 102 | +- deployment.yaml |
| 103 | +``` |
| 104 | + |
| 105 | +2. As declared in the `resources` field above, we need a k8s manifest `src/deployment.yaml`. |
| 106 | +Create it and set the `spec.containers[x].image` field as a fixed digest, example: |
| 107 | +```yaml |
| 108 | +spec: |
| 109 | + containers: |
| 110 | + - name: docker-test-pod |
| 111 | + image: toto04/testcontainer@sha256:b5ec2efcc11e90c2fd955cd1c01f3fdf7c2f18c77c213360addcd37be7e8f2f3 |
| 112 | +``` |
| 113 | + |
| 114 | +:::tip |
| 115 | +If you are using Docker Hub, you can find a digest going to the image homepage ([example](https://hub.docker.com/r/toto04/testcontainer/tags)) |
| 116 | +under the tag you want to use (e.g. `latest`) |
| 117 | +::: |
| 118 | + |
| 119 | +3. In the `config.json` file set the image(s) to automatically update: |
| 120 | +```yaml |
| 121 | + "image": { |
| 122 | + "image_list": "toto04/testcontainer:latest", |
| 123 | + "update_strategy": "digest" |
| 124 | + } |
| 125 | +``` |
| 126 | + |
| 127 | +In this configuration, the image `toto04/testcontainer` would be automatically updated following the tag `latest`. |
| 128 | + |
| 129 | + |
| 130 | + |
| 131 | +:::tip |
| 132 | +You can also specify multiple images to update: |
| 133 | +```yaml title="config.json" |
| 134 | + "image": { |
| 135 | +# add-highlight-start |
| 136 | + "image_list": "x/image1:latest x/image2:latest", |
| 137 | +# add-highlight-end |
| 138 | + "update_strategy": "digest" |
| 139 | + } |
| 140 | +``` |
| 141 | + |
| 142 | +```yaml title="src/deployment.yaml" |
| 143 | +apiVersion: apps/v1 |
| 144 | +kind: Deployment |
| 145 | +metadata: |
| 146 | + name: deploy-1 |
| 147 | + namespace: <k8s-namespace> |
| 148 | +spec: |
| 149 | + replicas: 1 |
| 150 | + selector: |
| 151 | + matchLabels: |
| 152 | + app: app-1 |
| 153 | + template: |
| 154 | + metadata: |
| 155 | + labels: |
| 156 | + app: app-1 |
| 157 | + spec: |
| 158 | + containers: |
| 159 | + - name: app-1-pod |
| 160 | +# add-highlight-start |
| 161 | + image: x/image1@sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| 162 | +# add-highlight-end |
| 163 | +--- |
| 164 | +apiVersion: apps/v1 |
| 165 | +kind: Deployment |
| 166 | +metadata: |
| 167 | + name: deploy-2 |
| 168 | + namespace: <k8s-namespace> |
| 169 | +spec: |
| 170 | + replicas: 2 |
| 171 | + selector: |
| 172 | + matchLabels: |
| 173 | + app: app-2 |
| 174 | + template: |
| 175 | + metadata: |
| 176 | + labels: |
| 177 | + app: app-2 |
| 178 | + spec: |
| 179 | + containers: |
| 180 | + - name: app-2-pod |
| 181 | +# add-highlight-start |
| 182 | + image: x/image2@sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| 183 | +# add-highlight-end |
| 184 | +``` |
| 185 | +::: |
0 commit comments