github.com/projectcontour/contour@v1.28.2/site/content/resources/upgrading.md (about) 1 --- 2 title: Upgrading Contour 3 layout: page 4 --- 5 6 <!-- NOTE: this document should be formatted with one sentence per line to made reviewing easier. --> 7 8 This document describes the changes needed to upgrade your Contour installation. 9 10 <div id="toc" class="navigation"></div> 11 12 # Before you start 13 14 Contour currently only tests sequential upgrades, i.e. without skipping any minor or patch versions. 15 This approach is recommended for users in order to minimize downtime and avoid any potential issues. 16 If you choose to skip versions while upgrading, please note that this may lead to additional downtime. 17 18 # Known issues 19 20 1. Envoy pod stuck in pending state 21 22 If Envoy is deployed with a Deployment and the number of envoy instances is not less than number of kubernetes nodes in the clusters, during rolling upgrade, new envoy pod will be stuck in pending stage because old envoy pod is occupying host port. 23 24 Workaround: Delete the envoy instance of older version manually. This will cause a little bit of downtime but it's pretty short. 25 26 # The easy way to upgrade 27 28 If the following are true for you: 29 30 * Your installation is in the `projectcontour` namespace. 31 * You are using our [quickstart example][18] deployments. 32 * Your cluster can take a few minutes of downtime. 33 34 Then the simplest way to upgrade is to delete the `projectcontour` namespace and reapply one of the example configurations: 35 36 ```bash 37 $ export CONTOUR_VERSION=<desired version, e.g. v1.24.0> 38 $ kubectl delete namespace projectcontour 39 $ kubectl apply -f {{< param base_url >}}/quickstart/$CONTOUR_VERSION/contour.yaml 40 ``` 41 42 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 43 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 44 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 45 46 # The less easy way 47 48 This section contains information for administrators who wish to upgrade the Contour resources one-by-one. 49 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the tag for the target version. 50 51 1. Update the Contour CRDs: 52 53 ```bash 54 $ kubectl apply -f examples/contour/01-crds.yaml 55 ``` 56 57 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 58 This will rotate the TLS certificates used for gRPC security. 59 60 ```bash 61 $ kubectl apply -f examples/contour/02-job-certgen.yaml 62 ``` 63 64 1. Update the Contour RBAC resources: 65 66 ```bash 67 $ kubectl apply -f examples/contour/02-rbac.yaml 68 $ kubectl apply -f examples/contour/02-role-contour.yaml 69 ``` 70 71 1. Upgrade the Contour deployment: 72 73 ```bash 74 $ kubectl apply -f examples/contour/03-contour.yaml 75 ``` 76 77 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 78 79 ```bash 80 $ kubectl apply -f examples/contour/03-envoy.yaml 81 ``` 82 83 # Legacy per-version upgrade instructions 84 85 Contour previously published per-version upgrade instructions which are retained below for posterity. 86 These will no longer be updated going forward, as the instructions were largely redundant between versions. 87 88 ## Upgrading Contour 1.23.2 to 1.24.0 89 90 Contour 1.24.0 is the current stable release. 91 92 ### Required Envoy version 93 94 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.25.0`. 95 96 Please see the [Envoy Release Notes][46] for information about the changes included in Envoy 1.25.0. 97 98 ### The easy way to upgrade 99 100 If the following are true for you: 101 102 * Your installation is in the `projectcontour` namespace. 103 * You are using our [quickstart example][18] deployments. 104 * Your cluster can take a few minutes of downtime. 105 106 Then the simplest way to upgrade to 1.24.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 107 108 ```bash 109 $ kubectl delete namespace projectcontour 110 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.24.0/contour.yaml 111 ``` 112 113 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 114 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 115 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 116 117 ### The less easy way 118 119 This section contains information for administrators who wish to apply the Contour 1.23.2 to 1.24.0 changes manually. 120 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.24.0` tag. 121 122 If your version of Contour is older than v1.23.2, please upgrade to v1.23.2 first, then upgrade to v1.24.0. 123 124 1. Update the Contour CRDs: 125 126 ```bash 127 $ kubectl apply -f examples/contour/01-crds.yaml 128 ``` 129 130 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 131 This will rotate the TLS certificates used for gRPC security. 132 133 ```bash 134 $ kubectl apply -f examples/contour/02-job-certgen.yaml 135 ``` 136 137 1. Update the Contour RBAC resources: 138 139 ```bash 140 $ kubectl apply -f examples/contour/02-rbac.yaml 141 $ kubectl apply -f examples/contour/02-role-contour.yaml 142 ``` 143 144 1. Upgrade the Contour deployment: 145 146 ```bash 147 $ kubectl apply -f examples/contour/03-contour.yaml 148 ``` 149 150 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 151 152 ```bash 153 $ kubectl apply -f examples/contour/03-envoy.yaml 154 ``` 155 156 ## Upgrading Contour 1.23.1 to 1.23.2 157 158 ### Required Envoy version 159 160 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.24.1`. 161 162 Please see the [Envoy Release Notes][45] for information about the changes included in Envoy 1.24.1. 163 164 ### The easy way to upgrade 165 166 If the following are true for you: 167 168 * Your installation is in the `projectcontour` namespace. 169 * You are using our [quickstart example][18] deployments. 170 * Your cluster can take a few minutes of downtime. 171 172 Then the simplest way to upgrade to 1.23.2 is to delete the `projectcontour` namespace and reapply one of the example configurations: 173 174 ```bash 175 $ kubectl delete namespace projectcontour 176 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.23.2/contour.yaml 177 ``` 178 179 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 180 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 181 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 182 183 ### The less easy way 184 185 This section contains information for administrators who wish to apply the Contour 1.23.1 to 1.23.2 changes manually. 186 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.23.2` tag. 187 188 If your version of Contour is older than v1.23.1, please upgrade to v1.23.1 first, then upgrade to v1.23.2. 189 190 1. Update the Contour CRDs: 191 192 ```bash 193 $ kubectl apply -f examples/contour/01-crds.yaml 194 ``` 195 196 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 197 This will rotate the TLS certificates used for gRPC security. 198 199 ```bash 200 $ kubectl apply -f examples/contour/02-job-certgen.yaml 201 ``` 202 203 1. Update the Contour RBAC resources: 204 205 ```bash 206 $ kubectl apply -f examples/contour/02-rbac.yaml 207 $ kubectl apply -f examples/contour/02-role-contour.yaml 208 ``` 209 210 1. Upgrade the Contour deployment: 211 212 ```bash 213 $ kubectl apply -f examples/contour/03-contour.yaml 214 ``` 215 216 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 217 218 ```bash 219 $ kubectl apply -f examples/contour/03-envoy.yaml 220 ``` 221 222 ## Upgrading Contour 1.23.0 to 1.23.1 223 224 ### Required Envoy version 225 226 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.24.1`. 227 228 Please see the [Envoy Release Notes][45] for information about the changes included in Envoy 1.24.1. 229 230 ### The easy way to upgrade 231 232 If the following are true for you: 233 234 * Your installation is in the `projectcontour` namespace. 235 * You are using our [quickstart example][18] deployments. 236 * Your cluster can take a few minutes of downtime. 237 238 Then the simplest way to upgrade to 1.23.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 239 240 ```bash 241 $ kubectl delete namespace projectcontour 242 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.23.1/contour.yaml 243 ``` 244 245 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 246 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 247 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 248 249 ### The less easy way 250 251 This section contains information for administrators who wish to apply the Contour 1.23.0 to 1.23.1 changes manually. 252 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.23.1` tag. 253 254 If your version of Contour is older than v1.23.0, please upgrade to v1.23.0 first, then upgrade to v1.23.1. 255 256 1. Update the Contour CRDs: 257 258 ```bash 259 $ kubectl apply -f examples/contour/01-crds.yaml 260 ``` 261 262 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 263 This will rotate the TLS certificates used for gRPC security. 264 265 ```bash 266 $ kubectl apply -f examples/contour/02-job-certgen.yaml 267 ``` 268 269 1. Update the Contour RBAC resources: 270 271 ```bash 272 $ kubectl apply -f examples/contour/02-rbac.yaml 273 $ kubectl apply -f examples/contour/02-role-contour.yaml 274 ``` 275 276 1. Upgrade the Contour deployment: 277 278 ```bash 279 $ kubectl apply -f examples/contour/03-contour.yaml 280 ``` 281 282 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 283 284 ```bash 285 $ kubectl apply -f examples/contour/03-envoy.yaml 286 ``` 287 288 ## Upgrading Contour 1.22.3 to 1.23.0 289 290 ### Required Envoy version 291 292 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.24.0`. 293 294 Please see the [Envoy Release Notes][42] for information about the changes included in Envoy 1.24.0. 295 296 ### The easy way to upgrade 297 298 If the following are true for you: 299 300 * Your installation is in the `projectcontour` namespace. 301 * You are using our [quickstart example][18] deployments. 302 * Your cluster can take a few minutes of downtime. 303 304 Then the simplest way to upgrade to 1.23.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 305 306 ```bash 307 $ kubectl delete namespace projectcontour 308 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.23.0/contour.yaml 309 ``` 310 311 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 312 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 313 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 314 315 ### The less easy way 316 317 This section contains information for administrators who wish to apply the Contour 1.22.3 to 1.23.0 changes manually. 318 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.23.0` tag. 319 320 If your version of Contour is older than v1.22.3, please upgrade to v1.22.3 first, then upgrade to v1.23.0. 321 322 1. Update the Contour CRDs: 323 324 ```bash 325 $ kubectl apply -f examples/contour/01-crds.yaml 326 ``` 327 328 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 329 This will rotate the TLS certificates used for gRPC security. 330 331 ```bash 332 $ kubectl apply -f examples/contour/02-job-certgen.yaml 333 ``` 334 335 1. Update the Contour RBAC resources: 336 337 ```bash 338 $ kubectl apply -f examples/contour/02-rbac.yaml 339 $ kubectl apply -f examples/contour/02-role-contour.yaml 340 ``` 341 342 1. Upgrade the Contour deployment: 343 344 ```bash 345 $ kubectl apply -f examples/contour/03-contour.yaml 346 ``` 347 348 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 349 350 ```bash 351 $ kubectl apply -f examples/contour/03-envoy.yaml 352 ``` 353 354 ## Upgrading Contour 1.22.2 to 1.22.3 355 356 ### Required Envoy version 357 358 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.23.3`. 359 360 Please see the [Envoy Release Notes][44] for information about the changes included in Envoy 1.23.3. 361 362 ### The easy way to upgrade 363 364 If the following are true for you: 365 366 * Your installation is in the `projectcontour` namespace. 367 * You are using our [quickstart example][18] deployments. 368 * Your cluster can take a few minutes of downtime. 369 370 Then the simplest way to upgrade to 1.22.3 is to delete the `projectcontour` namespace and reapply one of the example configurations: 371 372 ```bash 373 $ kubectl delete namespace projectcontour 374 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.22.3/contour.yaml 375 ``` 376 377 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 378 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 379 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 380 381 ### The less easy way 382 383 This section contains information for administrators who wish to apply the Contour 1.22.2 to 1.22.3 changes manually. 384 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.22.3` tag. 385 386 If your version of Contour is older than v1.22.2, please upgrade to v1.22.2 first, then upgrade to v1.22.3. 387 388 1. Update the Contour CRDs: 389 390 ```bash 391 $ kubectl apply -f examples/contour/01-crds.yaml 392 ``` 393 394 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 395 This will rotate the TLS certificates used for gRPC security. 396 397 ```bash 398 $ kubectl apply -f examples/contour/02-job-certgen.yaml 399 ``` 400 401 1. Update the Contour RBAC resources: 402 403 ```bash 404 $ kubectl apply -f examples/contour/02-rbac.yaml 405 $ kubectl apply -f examples/contour/02-role-contour.yaml 406 ``` 407 408 1. Upgrade the Contour deployment: 409 410 ```bash 411 $ kubectl apply -f examples/contour/03-contour.yaml 412 ``` 413 414 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 415 416 ```bash 417 $ kubectl apply -f examples/contour/03-envoy.yaml 418 ``` 419 420 ## Upgrading Contour 1.22.1 to 1.22.2 421 422 ### Required Envoy version 423 424 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.23.3`. 425 426 Please see the [Envoy Release Notes][44] for information about the changes included in Envoy 1.23.3. 427 428 ### The easy way to upgrade 429 430 If the following are true for you: 431 432 * Your installation is in the `projectcontour` namespace. 433 * You are using our [quickstart example][18] deployments. 434 * Your cluster can take a few minutes of downtime. 435 436 Then the simplest way to upgrade to 1.22.2 is to delete the `projectcontour` namespace and reapply one of the example configurations: 437 438 ```bash 439 $ kubectl delete namespace projectcontour 440 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.22.2/contour.yaml 441 ``` 442 443 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 444 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 445 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 446 447 ### The less easy way 448 449 This section contains information for administrators who wish to apply the Contour 1.22.1 to 1.22.2 changes manually. 450 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.22.2` tag. 451 452 If your version of Contour is older than v1.22.1, please upgrade to v1.22.1 first, then upgrade to v1.22.2. 453 454 1. Update the Contour CRDs: 455 456 ```bash 457 $ kubectl apply -f examples/contour/01-crds.yaml 458 ``` 459 460 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 461 This will rotate the TLS certificates used for gRPC security. 462 463 ```bash 464 $ kubectl apply -f examples/contour/02-job-certgen.yaml 465 ``` 466 467 1. Update the Contour RBAC resources: 468 469 ```bash 470 $ kubectl apply -f examples/contour/02-rbac.yaml 471 $ kubectl apply -f examples/contour/02-role-contour.yaml 472 ``` 473 474 1. Upgrade the Contour deployment: 475 476 ```bash 477 $ kubectl apply -f examples/contour/03-contour.yaml 478 ``` 479 480 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 481 482 ```bash 483 $ kubectl apply -f examples/contour/03-envoy.yaml 484 ``` 485 486 ## Upgrading Contour 1.22.0 to 1.22.1 487 488 ### Required Envoy version 489 490 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.23.1`. 491 492 Please see the [Envoy Release Notes][41] for information about the changes included in Envoy 1.23.1. 493 494 ### The easy way to upgrade 495 496 If the following are true for you: 497 498 * Your installation is in the `projectcontour` namespace. 499 * You are using our [quickstart example][18] deployments. 500 * Your cluster can take a few minutes of downtime. 501 502 Then the simplest way to upgrade to 1.22.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 503 504 ```bash 505 $ kubectl delete namespace projectcontour 506 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.22.1/contour.yaml 507 ``` 508 509 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 510 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 511 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 512 513 ### The less easy way 514 515 This section contains information for administrators who wish to apply the Contour 1.22.0 to 1.22.1 changes manually. 516 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.22.1` tag. 517 518 If your version of Contour is older than v1.22.0, please upgrade to v1.22.0 first, then upgrade to v1.22.1. 519 520 1. Update the Contour CRDs: 521 522 ```bash 523 $ kubectl apply -f examples/contour/01-crds.yaml 524 ``` 525 526 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 527 This will rotate the TLS certificates used for gRPC security. 528 529 ```bash 530 $ kubectl apply -f examples/contour/02-job-certgen.yaml 531 ``` 532 533 1. Update the Contour RBAC resources: 534 535 ```bash 536 $ kubectl apply -f examples/contour/02-rbac.yaml 537 $ kubectl apply -f examples/contour/02-role-contour.yaml 538 ``` 539 540 1. Upgrade the Contour deployment: 541 542 ```bash 543 $ kubectl apply -f examples/contour/03-contour.yaml 544 ``` 545 546 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 547 548 ```bash 549 $ kubectl apply -f examples/contour/03-envoy.yaml 550 ``` 551 552 ## Upgrading Contour 1.21.3 to 1.22.0 553 554 ### Required Envoy version 555 556 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.23.0`. 557 558 Please see the [Envoy Release Notes][40] for information about the changes included in Envoy 1.23.0. 559 560 ### The easy way to upgrade 561 562 If the following are true for you: 563 564 * Your installation is in the `projectcontour` namespace. 565 * You are using our [quickstart example][18] deployments. 566 * Your cluster can take a few minutes of downtime. 567 568 Then the simplest way to upgrade to 1.22.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 569 570 ```bash 571 $ kubectl delete namespace projectcontour 572 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.22.0/contour.yaml 573 ``` 574 575 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 576 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 577 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 578 579 ### The less easy way 580 581 This section contains information for administrators who wish to apply the Contour 1.21.3 to 1.22.0 changes manually. 582 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.22.0` tag. 583 584 If your version of Contour is older than v1.21.3, please upgrade to v1.21.3 first, then upgrade to v1.22.0. 585 586 1. Update the Contour CRDs: 587 588 ```bash 589 $ kubectl apply -f examples/contour/01-crds.yaml 590 ``` 591 592 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 593 This will rotate the TLS certificates used for gRPC security. 594 595 ```bash 596 $ kubectl apply -f examples/contour/02-job-certgen.yaml 597 ``` 598 599 1. Update the Contour RBAC resources: 600 601 ```bash 602 $ kubectl apply -f examples/contour/02-rbac.yaml 603 $ kubectl apply -f examples/contour/02-role-contour.yaml 604 ``` 605 606 1. Upgrade the Contour deployment: 607 608 ```bash 609 $ kubectl apply -f examples/contour/03-contour.yaml 610 ``` 611 612 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 613 614 ```bash 615 $ kubectl apply -f examples/contour/03-envoy.yaml 616 ``` 617 618 ## Upgrading Contour 1.21.2 to 1.21.3 619 620 ### Required Envoy version 621 622 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.22.6`. 623 624 Please see the [Envoy Release Notes][43] for information about the changes included in Envoy 1.22.6. 625 626 ### The easy way to upgrade 627 628 If the following are true for you: 629 630 * Your installation is in the `projectcontour` namespace. 631 * You are using our [quickstart example][18] deployments. 632 * Your cluster can take a few minutes of downtime. 633 634 Then the simplest way to upgrade to 1.21.3 is to delete the `projectcontour` namespace and reapply one of the example configurations: 635 636 ```bash 637 $ kubectl delete namespace projectcontour 638 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.21.3/contour.yaml 639 ``` 640 641 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 642 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 643 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 644 645 ### The less easy way 646 647 This section contains information for administrators who wish to apply the Contour 1.21.2 to 1.21.3 changes manually. 648 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.21.3` tag. 649 650 If your version of Contour is older than v1.21.2, please upgrade to v1.21.2 first, then upgrade to v1.21.3. 651 652 1. Update the Contour CRDs: 653 654 ```bash 655 $ kubectl apply -f examples/contour/01-crds.yaml 656 ``` 657 658 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 659 This will rotate the TLS certificates used for gRPC security. 660 661 ```bash 662 $ kubectl apply -f examples/contour/02-job-certgen.yaml 663 ``` 664 665 1. Update the Contour RBAC resources: 666 667 ```bash 668 $ kubectl apply -f examples/contour/02-rbac.yaml 669 $ kubectl apply -f examples/contour/02-role-contour.yaml 670 ``` 671 672 1. Upgrade the Contour deployment: 673 674 ```bash 675 $ kubectl apply -f examples/contour/03-contour.yaml 676 ``` 677 678 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 679 680 ```bash 681 $ kubectl apply -f examples/contour/03-envoy.yaml 682 ``` 683 684 ## Upgrading Contour 1.21.1 to 1.21.2 685 686 ### Required Envoy version 687 688 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.22.6`. 689 690 Please see the [Envoy Release Notes][43] for information about the changes included in Envoy 1.22.6. 691 692 ### The easy way to upgrade 693 694 If the following are true for you: 695 696 * Your installation is in the `projectcontour` namespace. 697 * You are using our [quickstart example][18] deployments. 698 * Your cluster can take a few minutes of downtime. 699 700 Then the simplest way to upgrade to 1.21.2 is to delete the `projectcontour` namespace and reapply one of the example configurations: 701 702 ```bash 703 $ kubectl delete namespace projectcontour 704 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.21.2/contour.yaml 705 ``` 706 707 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 708 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 709 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 710 711 ### The less easy way 712 713 This section contains information for administrators who wish to apply the Contour 1.21.1 to 1.21.2 changes manually. 714 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.21.2` tag. 715 716 If your version of Contour is older than v1.21.1, please upgrade to v1.21.1 first, then upgrade to v1.21.2. 717 718 1. Update the Contour CRDs: 719 720 ```bash 721 $ kubectl apply -f examples/contour/01-crds.yaml 722 ``` 723 724 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 725 This will rotate the TLS certificates used for gRPC security. 726 727 ```bash 728 $ kubectl apply -f examples/contour/02-job-certgen.yaml 729 ``` 730 731 1. Update the Contour RBAC resources: 732 733 ```bash 734 $ kubectl apply -f examples/contour/02-rbac.yaml 735 $ kubectl apply -f examples/contour/02-role-contour.yaml 736 ``` 737 738 1. Upgrade the Contour deployment: 739 740 ```bash 741 $ kubectl apply -f examples/contour/03-contour.yaml 742 ``` 743 744 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 745 746 ```bash 747 $ kubectl apply -f examples/contour/03-envoy.yaml 748 ``` 749 750 751 ## Upgrading Contour 1.21.0 to 1.21.1 752 753 ### Required Envoy version 754 755 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.22.2`. 756 757 Please see the [Envoy Release Notes][38] for information about the changes included in Envoy 1.22.2. 758 759 ### The easy way to upgrade 760 761 If the following are true for you: 762 763 * Your installation is in the `projectcontour` namespace. 764 * You are using our [quickstart example][18] deployments. 765 * Your cluster can take a few minutes of downtime. 766 767 Then the simplest way to upgrade to 1.21.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 768 769 ```bash 770 $ kubectl delete namespace projectcontour 771 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.21.1/contour.yaml 772 ``` 773 774 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 775 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 776 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 777 778 ### The less easy way 779 780 This section contains information for administrators who wish to apply the Contour 1.21.0 to 1.21.1 changes manually. 781 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.21.1` tag. 782 783 If your version of Contour is older than v1.21.0, please upgrade to v1.21.0 first, then upgrade to v1.21.1. 784 785 1. Update the Contour CRDs: 786 787 ```bash 788 $ kubectl apply -f examples/contour/01-crds.yaml 789 ``` 790 791 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 792 This will rotate the TLS certificates used for gRPC security. 793 794 ```bash 795 $ kubectl apply -f examples/contour/02-job-certgen.yaml 796 ``` 797 798 1. Update the Contour RBAC resources: 799 800 ```bash 801 $ kubectl apply -f examples/contour/02-rbac.yaml 802 $ kubectl apply -f examples/contour/02-role-contour.yaml 803 ``` 804 805 1. Upgrade the Contour deployment: 806 807 ```bash 808 $ kubectl apply -f examples/contour/03-contour.yaml 809 ``` 810 811 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 812 813 ```bash 814 $ kubectl apply -f examples/contour/03-envoy.yaml 815 ``` 816 817 ## Upgrading Contour 1.20.2 to 1.21.0 818 819 ### Required Envoy version 820 821 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.22.0`. 822 823 Please see the [Envoy Release Notes][37] for information about the changes included in Envoy 1.22.0. 824 825 ### The easy way to upgrade 826 827 If the following are true for you: 828 829 * Your installation is in the `projectcontour` namespace. 830 * You are using our [quickstart example][18] deployments. 831 * Your cluster can take a few minutes of downtime. 832 833 Then the simplest way to upgrade to 1.21.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 834 835 ```bash 836 $ kubectl delete namespace projectcontour 837 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.21.0/contour.yaml 838 ``` 839 840 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 841 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 842 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 843 844 ### The less easy way 845 846 This section contains information for administrators who wish to apply the Contour 1.20.2 to 1.21.0 changes manually. 847 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.21.0` tag. 848 849 If your version of Contour is older than v1.20.2, please upgrade to v1.20.2 first, then upgrade to v1.21.0. 850 851 1. Update the Contour CRDs: 852 853 ```bash 854 $ kubectl apply -f examples/contour/01-crds.yaml 855 ``` 856 857 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 858 This will rotate the TLS certificates used for gRPC security. 859 860 ```bash 861 $ kubectl apply -f examples/contour/02-job-certgen.yaml 862 ``` 863 864 1. Update the Contour RBAC resources: 865 866 ```bash 867 $ kubectl apply -f examples/contour/02-rbac.yaml 868 $ kubectl apply -f examples/contour/02-role-contour.yaml 869 ``` 870 871 1. Upgrade the Contour deployment: 872 873 ```bash 874 $ kubectl apply -f examples/contour/03-contour.yaml 875 ``` 876 877 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 878 879 ```bash 880 $ kubectl apply -f examples/contour/03-envoy.yaml 881 ``` 882 883 ## Upgrading Contour 1.20.1 to 1.20.2 884 885 ### Required Envoy version 886 887 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.21.3`. 888 889 Please see the [Envoy Release Notes][39] for information about issues fixed in Envoy 1.21.3. 890 891 ### The easy way to upgrade 892 893 If the following are true for you: 894 895 * Your installation is in the `projectcontour` namespace. 896 * You are using our [quickstart example][18] deployments. 897 * Your cluster can take a few minutes of downtime. 898 899 Then the simplest way to upgrade to 1.20.2 is to delete the `projectcontour` namespace and reapply one of the example configurations: 900 901 ```bash 902 $ kubectl delete namespace projectcontour 903 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.20.2/contour.yaml 904 ``` 905 906 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 907 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 908 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 909 910 ### The less easy way 911 912 This section contains information for administrators who wish to apply the Contour 1.20.1 to 1.20.2 changes manually. 913 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.20.2` tag. 914 915 If your version of Contour is older than v1.20.1, please upgrade to v1.20.1 first, then upgrade to v1.20.2. 916 917 1. Update the Contour CRDs: 918 919 ```bash 920 $ kubectl apply -f examples/contour/01-crds.yaml 921 ``` 922 923 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 924 This will rotate the TLS certificates used for gRPC security. 925 926 ```bash 927 $ kubectl apply -f examples/contour/02-job-certgen.yaml 928 ``` 929 930 1. Update the Contour cluster role: 931 932 ```bash 933 $ kubectl apply -f examples/contour/02-role-contour.yaml 934 ``` 935 936 1. Upgrade the Contour deployment: 937 938 ```bash 939 $ kubectl apply -f examples/contour/03-contour.yaml 940 ``` 941 942 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 943 944 ```bash 945 $ kubectl apply -f examples/contour/03-envoy.yaml 946 ``` 947 948 949 ## Upgrading Contour 1.20.0 to 1.20.1 950 951 ### Required Envoy version 952 953 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.21.1`. 954 955 Please see the [Envoy Release Notes][36] for information about issues fixed in Envoy 1.21.1. 956 957 ### The easy way to upgrade 958 959 If the following are true for you: 960 961 * Your installation is in the `projectcontour` namespace. 962 * You are using our [quickstart example][18] deployments. 963 * Your cluster can take a few minutes of downtime. 964 965 Then the simplest way to upgrade to 1.20.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 966 967 ```bash 968 $ kubectl delete namespace projectcontour 969 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.20.1/contour.yaml 970 ``` 971 972 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 973 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 974 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 975 976 ### The less easy way 977 978 This section contains information for administrators who wish to apply the Contour 1.20.0 to 1.20.1 changes manually. 979 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.20.1` tag. 980 981 If your version of Contour is older than v1.20.0, please upgrade to v1.20.0 first, then upgrade to v1.20.1. 982 983 1. Update the Contour CRDs: 984 985 ```bash 986 $ kubectl apply -f examples/contour/01-crds.yaml 987 ``` 988 989 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 990 This will rotate the TLS certificates used for gRPC security. 991 992 ```bash 993 $ kubectl apply -f examples/contour/02-job-certgen.yaml 994 ``` 995 996 1. Update the Contour cluster role: 997 998 ```bash 999 $ kubectl apply -f examples/contour/02-role-contour.yaml 1000 ``` 1001 1002 1. Upgrade the Contour deployment: 1003 1004 ```bash 1005 $ kubectl apply -f examples/contour/03-contour.yaml 1006 ``` 1007 1008 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1009 1010 ```bash 1011 $ kubectl apply -f examples/contour/03-envoy.yaml 1012 ``` 1013 1014 ## Upgrading Contour 1.19.1 to 1.20.0 1015 1016 ### Required Envoy version 1017 1018 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.21.0`. 1019 1020 Please see the [Envoy Release Notes][35] for information about issues fixed in Envoy 1.21.0. 1021 1022 ### The easy way to upgrade 1023 1024 If the following are true for you: 1025 1026 * Your installation is in the `projectcontour` namespace. 1027 * You are using our [quickstart example][18] deployments. 1028 * Your cluster can take a few minutes of downtime. 1029 1030 Then the simplest way to upgrade to 1.20.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1031 1032 ```bash 1033 $ kubectl delete namespace projectcontour 1034 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.20.0/contour.yaml 1035 ``` 1036 1037 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1038 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1039 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1040 1041 ### The less easy way 1042 1043 This section contains information for administrators who wish to apply the Contour 1.19.1 to 1.20.0 changes manually. 1044 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.20.0` tag. 1045 1046 If your version of Contour is older than v1.19.1, please upgrade to v1.19.1 first, then upgrade to v1.20.0. 1047 1048 1. Update the Contour CRDs: 1049 1050 ```bash 1051 $ kubectl apply -f examples/contour/01-crds.yaml 1052 ``` 1053 1054 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1055 This will rotate the TLS certificates used for gRPC security. 1056 1057 ```bash 1058 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1059 ``` 1060 1061 1. Update the Contour cluster role: 1062 1063 ```bash 1064 $ kubectl apply -f examples/contour/02-role-contour.yaml 1065 ``` 1066 1067 1. Upgrade the Contour deployment: 1068 1069 ```bash 1070 $ kubectl apply -f examples/contour/03-contour.yaml 1071 ``` 1072 1073 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1074 1075 ```bash 1076 $ kubectl apply -f examples/contour/03-envoy.yaml 1077 ``` 1078 1079 ## Upgrading Contour 1.19.0 to 1.19.1 1080 1081 ### Required Envoy version 1082 1083 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.19.1`. 1084 1085 Please see the [Envoy Release Notes][34] for information about issues fixed in Envoy 1.19.1. 1086 1087 ### The easy way to upgrade 1088 1089 If the following are true for you: 1090 1091 * Your installation is in the `projectcontour` namespace. 1092 * You are using our [quickstart example][18] deployments. 1093 * Your cluster can take a few minutes of downtime. 1094 1095 Then the simplest way to upgrade to 1.19.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1096 1097 ```bash 1098 $ kubectl delete namespace projectcontour 1099 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.19.1/contour.yaml 1100 ``` 1101 1102 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1103 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1104 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1105 1106 ### The less easy way 1107 1108 This section contains information for administrators who wish to apply the Contour 1.19.0 to 1.19.1 changes manually. 1109 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.19.1` tag. 1110 1111 If your version of Contour is older than v1.19.0, please upgrade to v1.19.0 first, then upgrade to v1.19.1. 1112 1113 1. Update the Contour CRDs: 1114 1115 ```bash 1116 $ kubectl apply -f examples/contour/01-crds.yaml 1117 ``` 1118 1119 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1120 This will rotate the TLS certificates used for gRPC security. 1121 1122 ```bash 1123 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1124 ``` 1125 1126 1. Update the Contour cluster role: 1127 1128 ```bash 1129 $ kubectl apply -f examples/contour/02-role-contour.yaml 1130 ``` 1131 1132 1. Upgrade the Contour deployment: 1133 1134 ```bash 1135 $ kubectl apply -f examples/contour/03-contour.yaml 1136 ``` 1137 1138 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1139 1140 ```bash 1141 $ kubectl apply -f examples/contour/03-envoy.yaml 1142 ``` 1143 1144 ## Upgrading Contour 1.18.3 to 1.19.0 1145 1146 ### Required Envoy version 1147 1148 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.19.1`. 1149 1150 Please see the [Envoy Release Notes][34] for information about issues fixed in Envoy 1.19.1. 1151 1152 ### The easy way to upgrade 1153 1154 If the following are true for you: 1155 1156 * Your installation is in the `projectcontour` namespace. 1157 * You are using our [quickstart example][18] deployments. 1158 * Your cluster can take a few minutes of downtime. 1159 1160 Then the simplest way to upgrade to 1.19.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1161 1162 ```bash 1163 $ kubectl delete namespace projectcontour 1164 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.19.0/contour.yaml 1165 ``` 1166 1167 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1168 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1169 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1170 1171 ### The less easy way 1172 1173 This section contains information for administrators who wish to apply the Contour 1.18.3 to 1.19.0 changes manually. 1174 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.19.0` tag. 1175 1176 If your version of Contour is older than v1.18.3, please upgrade to v1.18.3 first, then upgrade to v1.19.0. 1177 1178 1. Update the Contour CRDs: 1179 1180 ```bash 1181 $ kubectl apply -f examples/contour/01-crds.yaml 1182 ``` 1183 1184 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1185 This will rotate the TLS certificates used for gRPC security. 1186 1187 ```bash 1188 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1189 ``` 1190 1191 1. Update the Contour cluster role: 1192 1193 ```bash 1194 $ kubectl apply -f examples/contour/02-role-contour.yaml 1195 ``` 1196 1197 1. Upgrade the Contour deployment: 1198 1199 ```bash 1200 $ kubectl apply -f examples/contour/03-contour.yaml 1201 ``` 1202 1203 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1204 1205 ```bash 1206 $ kubectl apply -f examples/contour/03-envoy.yaml 1207 ``` 1208 1209 ## Upgrading Contour 1.18.2 to 1.18.3 1210 1211 ### Required Envoy version 1212 1213 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.19.1`. 1214 1215 Please see the [Envoy Release Notes][34] for information about issues fixed in Envoy 1.19.1. 1216 1217 ### The easy way to upgrade 1218 1219 If the following are true for you: 1220 1221 * Your installation is in the `projectcontour` namespace. 1222 * You are using our [quickstart example][18] deployments. 1223 * Your cluster can take a few minutes of downtime. 1224 1225 Then the simplest way to upgrade to 1.18.3 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1226 1227 ```bash 1228 $ kubectl delete namespace projectcontour 1229 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.18.3/contour.yaml 1230 ``` 1231 1232 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1233 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1234 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1235 1236 ### The less easy way 1237 1238 This section contains information for administrators who wish to apply the Contour 1.18.2 to 1.18.3 changes manually. 1239 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.18.3` tag. 1240 1241 If your version of Contour is older than v1.18.2, please upgrade to v1.18.2 first, then upgrade to v1.18.3. 1242 1243 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1244 This will rotate the TLS certificates used for gRPC security. 1245 1246 ```bash 1247 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1248 ``` 1249 1250 1. Update your RBAC definitions: 1251 1252 ```bash 1253 $ kubectl apply -f examples/contour/02-rbac.yaml 1254 ``` 1255 1256 1. Upgrade your Contour deployment: 1257 1258 ```bash 1259 $ kubectl apply -f examples/contour/03-contour.yaml 1260 ``` 1261 1262 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1263 1264 ```bash 1265 $ kubectl apply -f examples/contour/03-envoy.yaml 1266 ``` 1267 1268 1269 ## Upgrading Contour 1.18.1 to 1.18.2 1270 1271 ### Required Envoy version 1272 1273 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.19.1`. 1274 1275 Please see the [Envoy Release Notes][34] for information about issues fixed in Envoy 1.19.1. 1276 1277 ### The easy way to upgrade 1278 1279 If the following are true for you: 1280 1281 * Your installation is in the `projectcontour` namespace. 1282 * You are using our [quickstart example][18] deployments. 1283 * Your cluster can take a few minutes of downtime. 1284 1285 Then the simplest way to upgrade to 1.18.2 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1286 1287 ```bash 1288 $ kubectl delete namespace projectcontour 1289 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.18.2/contour.yaml 1290 ``` 1291 1292 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1293 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1294 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1295 1296 ### The less easy way 1297 1298 This section contains information for administrators who wish to apply the Contour 1.18.1 to 1.18.2 changes manually. 1299 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.18.2` tag. 1300 1301 If your version of Contour is older than v1.18.1, please upgrade to v1.18.1 first, then upgrade to v1.18.2. 1302 1303 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1304 This will rotate the TLS certificates used for gRPC security. 1305 1306 ```bash 1307 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1308 ``` 1309 1310 1. Update your RBAC definitions: 1311 1312 ```bash 1313 $ kubectl apply -f examples/contour/02-rbac.yaml 1314 ``` 1315 1316 1. Upgrade your Contour deployment: 1317 1318 ```bash 1319 $ kubectl apply -f examples/contour/03-contour.yaml 1320 ``` 1321 1322 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1323 1324 ```bash 1325 $ kubectl apply -f examples/contour/03-envoy.yaml 1326 ``` 1327 1328 ## Upgrading Contour 1.18.0 to 1.18.1 1329 1330 ### Required Envoy version 1331 1332 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.19.1`. 1333 1334 Please see the [Envoy Release Notes][34] for information about issues fixed in Envoy 1.19.1. 1335 1336 ### The easy way to upgrade 1337 1338 If the following are true for you: 1339 1340 * Your installation is in the `projectcontour` namespace. 1341 * You are using our [quickstart example][18] deployments. 1342 * Your cluster can take a few minutes of downtime. 1343 1344 Then the simplest way to upgrade to 1.18.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1345 1346 ```bash 1347 $ kubectl delete namespace projectcontour 1348 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.18.1/contour.yaml 1349 ``` 1350 1351 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1352 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1353 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1354 1355 ### The less easy way 1356 1357 This section contains information for administrators who wish to apply the Contour 1.18.0 to 1.18.1 changes manually. 1358 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.18.1` tag. 1359 1360 If your version of Contour is older than v1.18.0, please upgrade to v1.18.0 first, then upgrade to v1.18.1. 1361 1362 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1363 This will rotate the TLS certificates used for gRPC security. 1364 1365 ```bash 1366 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1367 ``` 1368 1369 1. Update your RBAC definitions: 1370 1371 ```bash 1372 $ kubectl apply -f examples/contour/02-rbac.yaml 1373 ``` 1374 1375 1. Upgrade your Contour deployment: 1376 1377 ```bash 1378 $ kubectl apply -f examples/contour/03-contour.yaml 1379 ``` 1380 1381 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1382 1383 ```bash 1384 $ kubectl apply -f examples/contour/03-envoy.yaml 1385 ``` 1386 1387 1388 ## Upgrading Contour 1.17.1 to 1.18.0 1389 1390 **If you utilize ExternalName services in your cluster, please note that this release disables Contour processing such services by default.** 1391 **Please see [this CVE](https://github.com/projectcontour/contour/security/advisories/GHSA-5ph6-qq5x-7jwc) for context and the [1.18.0 release notes](https://github.com/projectcontour/contour/releases/tag/v1.18.0).** 1392 1393 ### Required Envoy version 1394 1395 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.19.0`. 1396 1397 Please see the [Envoy Release Notes][33] for information about issues fixed in Envoy 1.19.0. 1398 1399 ### The easy way to upgrade 1400 1401 If the following are true for you: 1402 1403 * Your installation is in the `projectcontour` namespace. 1404 * You are using our [quickstart example][18] deployments. 1405 * Your cluster can take a few minutes of downtime. 1406 1407 Then the simplest way to upgrade to 1.18.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1408 1409 ```bash 1410 $ kubectl delete namespace projectcontour 1411 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.18.0/contour.yaml 1412 ``` 1413 1414 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1415 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1416 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1417 1418 ### The less easy way 1419 1420 This section contains information for administrators who wish to apply the Contour 1.17.1 to 1.18.0 changes manually. 1421 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.18.0` tag. 1422 1423 If your version of Contour is older than v1.17.1, please upgrade to v1.17.1 first, then upgrade to v1.18.0. 1424 1425 1. The Contour CRD definitions must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 1426 1427 ```bash 1428 $ kubectl apply -f examples/contour/01-crds.yaml 1429 ``` 1430 1431 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1432 This will rotate the TLS certificates used for gRPC security. 1433 1434 ```bash 1435 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1436 ``` 1437 1438 1. Update your RBAC definitions: 1439 1440 ```bash 1441 $ kubectl apply -f examples/contour/02-rbac.yaml 1442 ``` 1443 1444 1. Upgrade your Contour deployment: 1445 1446 ```bash 1447 $ kubectl apply -f examples/contour/03-contour.yaml 1448 ``` 1449 1450 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1451 1452 ```bash 1453 $ kubectl apply -f examples/contour/03-envoy.yaml 1454 ``` 1455 1456 ## Upgrading Contour 1.17.0 to 1.17.1 1457 1458 ### Required Envoy version 1459 1460 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.18.3`. 1461 1462 Please see the [Envoy Release Notes][32] for information about issues fixed in Envoy 1.18.3. 1463 1464 ### The easy way to upgrade 1465 1466 If the following are true for you: 1467 1468 * Your installation is in the `projectcontour` namespace. 1469 * You are using our [quickstart example][18] deployments. 1470 * Your cluster can take a few minutes of downtime. 1471 1472 Then the simplest way to upgrade to 1.17.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1473 1474 ```bash 1475 $ kubectl delete namespace projectcontour 1476 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.17.1/contour.yaml 1477 ``` 1478 1479 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1480 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1481 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1482 1483 ### The less easy way 1484 1485 This section contains information for administrators who wish to apply the Contour 1.17.0 to 1.17.1 changes manually. 1486 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.17.1` tag. 1487 1488 If your version of Contour is older than v1.17.0, please upgrade to v1.17.0 first, then upgrade to v1.17.1. 1489 1490 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1491 This will rotate the TLS certificates used for gRPC security. 1492 1493 ```bash 1494 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1495 ``` 1496 1497 1. Update your RBAC definitions: 1498 1499 ```bash 1500 $ kubectl apply -f examples/contour/02-rbac.yaml 1501 ``` 1502 1503 1. Upgrade your Contour deployment: 1504 1505 ```bash 1506 $ kubectl apply -f examples/contour/03-contour.yaml 1507 ``` 1508 1509 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1510 1511 ```bash 1512 $ kubectl apply -f examples/contour/03-envoy.yaml 1513 ``` 1514 1515 ## Upgrading Contour 1.16.0 to 1.17.0 1516 1517 ### Required Envoy version 1518 1519 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.18.3`. 1520 1521 Please see the [Envoy Release Notes][32] for information about issues fixed in Envoy 1.18.3. 1522 1523 ### The easiest way to upgrade (alpha) 1524 For existing Contour Operator users, complete the following steps to upgrade Contour: 1525 1526 - Verify the operator is running v1.16.0, and it's deployment status is "Available=True". 1527 - Verify the status of all Contour custom resources are "Available=True". 1528 - Update the operator's image to v1.17.0: 1529 ```bash 1530 $ kubectl patch deploy/contour-operator -n contour-operator -p '{"spec":{"template":{"spec":{"containers":[{"name":"contour-operator","image":"docker.io/projectcontour/contour-operator:v1.17.0"}]}}}}' 1531 ``` 1532 - The above command will upgrade the operator. After the operator runs the new version, it will upgrade Contour. 1533 - Verify the operator and Contour are running the new version. 1534 - Verify all Contour custom resources are "Available=True". 1535 1536 ### The easy way to upgrade 1537 1538 If the following are true for you: 1539 1540 * Your installation is in the `projectcontour` namespace. 1541 * You are using our [quickstart example][18] deployments. 1542 * Your cluster can take a few minutes of downtime. 1543 1544 Then the simplest way to upgrade to 1.17.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1545 1546 ```bash 1547 $ kubectl delete namespace projectcontour 1548 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.17.0/contour.yaml 1549 ``` 1550 1551 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1552 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1553 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1554 1555 ### The less easy way 1556 1557 This section contains information for administrators who wish to apply the Contour 1.16.0 to 1.17.0 changes manually. 1558 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.17.0` tag. 1559 1560 If your version of Contour is older than v1.16.0, please upgrade to v1.16.0 first, then upgrade to v1.17.0. 1561 1562 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in a format compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1563 This will rotate the TLS certificates used for gRPC security. 1564 1565 ```bash 1566 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1567 ``` 1568 1569 1. Update your RBAC definitions: 1570 1571 ```bash 1572 $ kubectl apply -f examples/contour/02-rbac.yaml 1573 ``` 1574 1575 1. Upgrade your Contour deployment: 1576 1577 ```bash 1578 $ kubectl apply -f examples/contour/03-contour.yaml 1579 ``` 1580 1581 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1582 1583 ```bash 1584 $ kubectl apply -f examples/contour/03-envoy.yaml 1585 ``` 1586 1587 1588 ## Upgrading Contour 1.15.1 to 1.16.0 1589 1590 ### Required Envoy version 1591 1592 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.18.3`. 1593 1594 Please see the [Envoy Release Notes][32] for information about issues fixed in Envoy 1.18.3. 1595 1596 ### The easiest way to upgrade (alpha) 1597 For existing Contour Operator users, complete the following steps to upgrade Contour: 1598 1599 - Verify the operator is running v1.15.1, and it's deployment status is "Available=True". 1600 - Verify the status of all Contour custom resources are "Available=True". 1601 - Update the operator's image to v1.16.0: 1602 ```bash 1603 $ kubectl patch deploy/contour-operator -n contour-operator -p '{"spec":{"template":{"spec":{"containers":[{"name":"contour-operator","image":"docker.io/projectcontour/contour-operator:v1.16.0"}]}}}}' 1604 ``` 1605 - The above command will upgrade the operator. After the operator runs the new version, it will upgrade Contour. 1606 - Verify the operator and Contour are running the new version. 1607 - Verify all Contour custom resources are "Available=True". 1608 1609 ### The easy way to upgrade 1610 1611 If the following are true for you: 1612 1613 * Your installation is in the `projectcontour` namespace. 1614 * You are using our [quickstart example][18] deployments. 1615 * Your cluster can take a few minutes of downtime. 1616 1617 Then the simplest way to upgrade to 1.16.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1618 1619 ```bash 1620 $ kubectl delete namespace projectcontour 1621 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.16.0/contour.yaml 1622 ``` 1623 1624 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1625 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1626 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1627 1628 ### The less easy way 1629 1630 This section contains information for administrators who wish to apply the Contour 1.15.1 to 1.16.0 changes manually. 1631 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.16.0` tag. 1632 1633 If your version of Contour is older than v1.15.1, please upgrade to v1.15.1 first, then upgrade to v1.16.0. 1634 1635 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1636 This will rotate the TLS certificates used for gRPC security. 1637 1638 ```bash 1639 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1640 ``` 1641 1642 1. Upgrade your Contour deployment: 1643 1644 ```bash 1645 $ kubectl apply -f examples/contour/03-contour.yaml 1646 ``` 1647 1648 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1649 1650 ```bash 1651 $ kubectl apply -f examples/contour/03-envoy.yaml 1652 ``` 1653 1654 ## Upgrading Contour 1.15.0 to 1.15.1 1655 1656 ### Required Envoy version 1657 1658 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.18.3`. 1659 1660 Please see the [Envoy Release Notes][32] for information about issues fixed in Envoy 1.18.3. 1661 1662 ### The easy way to upgrade 1663 1664 If the following are true for you: 1665 1666 * Your installation is in the `projectcontour` namespace. 1667 * You are using our [quickstart example][18] deployments. 1668 * Your cluster can take a few minutes of downtime. 1669 1670 Then the simplest way to upgrade to 1.15.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1671 1672 ```bash 1673 $ kubectl delete namespace projectcontour 1674 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.15.1/contour.yaml 1675 ``` 1676 1677 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1678 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1679 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1680 1681 ### The less easy way 1682 1683 This section contains information for administrators who wish to apply the Contour 1.15.0 to 1.15.01 changes manually. 1684 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.15.1` tag. 1685 1686 If your version of Contour is older than v1.15.0, please upgrade to v1.15.0 first, then upgrade to v1.15.1. 1687 1688 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1689 This will rotate the TLS certificates used for gRPC security. 1690 1691 ```bash 1692 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1693 ``` 1694 1695 1. Upgrade your Contour deployment: 1696 1697 ```bash 1698 $ kubectl apply -f examples/contour/03-contour.yaml 1699 ``` 1700 1701 1. Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1702 1703 ```bash 1704 $ kubectl apply -f examples/contour/03-envoy.yaml 1705 ``` 1706 1707 ## Upgrading Contour 1.14.1 to 1.15.0 1708 1709 ### Required Envoy version 1710 1711 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.18.2`. 1712 1713 Please see the [Envoy Release Notes][31] for information about issues fixed in Envoy 1.18.2. 1714 1715 ### The easy way to upgrade 1716 1717 If the following are true for you: 1718 1719 * Your installation is in the `projectcontour` namespace. 1720 * You are using our [quickstart example][18] deployments. 1721 * Your cluster can take a few minutes of downtime. 1722 1723 Then the simplest way to upgrade to 1.15.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1724 1725 ```bash 1726 $ kubectl delete namespace projectcontour 1727 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.15.0/contour.yaml 1728 ``` 1729 1730 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1731 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1732 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1733 1734 ### The less easy way 1735 1736 This section contains information for administrators who wish to apply the Contour 1.14.1 to 1.15.0 changes manually. 1737 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.15.0` tag. 1738 1739 If your version of Contour is older than v1.14, please upgrade to v1.14 first, then upgrade to v1.15.0. 1740 1741 1. The Contour CRD definitions must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 1742 1743 ```bash 1744 $ kubectl apply -f examples/contour/01-crds.yaml 1745 ``` 1746 1747 1. Users of the example deployment should reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1748 This will rotate the TLS certificates used for gRPC security. 1749 1750 ```bash 1751 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1752 ``` 1753 1754 1. This release includes an update to RBAC rules. Update the Contour ClusterRole with the following: 1755 1756 ```bash 1757 $ kubectl apply -f examples/contour/02-role-contour.yaml 1758 ``` 1759 1760 1. This release includes changes to support Ingress wildcard hosts that require Envoy to be upgraded *before* Contour. Update the Envoy DaemonSet: 1761 1762 ```bash 1763 $ kubectl apply -f examples/contour/03-envoy.yaml 1764 ``` 1765 1766 1. Once the Envoy DaemonSet has finished updating, upgrade your Contour deployment: 1767 1768 ```bash 1769 $ kubectl apply -f examples/contour/03-contour.yaml 1770 ``` 1771 1772 ## Upgrading Contour 1.14.0 to 1.14.1 1773 1774 ### Required Envoy version 1775 1776 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.17.2`. 1777 1778 Please see the [Envoy Release Notes][30] for information about issues fixed in Envoy 1.17.2. 1779 1780 ### The easy way to upgrade 1781 1782 If the following are true for you: 1783 1784 * Your installation is in the `projectcontour` namespace. 1785 * You are using our [quickstart example][18] deployments. 1786 * Your cluster can take a few minutes of downtime. 1787 1788 Then the simplest way to upgrade to 1.14.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1789 1790 ```bash 1791 $ kubectl delete namespace projectcontour 1792 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.14.1/contour.yaml 1793 ``` 1794 1795 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1796 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1797 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1798 1799 ### The less easy way 1800 1801 This section contains information for administrators who wish to apply the Contour 1.14.0 to 1.14.1 changes manually. 1802 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.14.1` tag. 1803 1804 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1805 This will rotate the TLS certificates used for gRPC security. 1806 1807 If your version of Contour is older than v1.14, please upgrade to v1.14 first, then upgrade to v1.14.1. 1808 1809 ```bash 1810 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1811 ``` 1812 1813 Upgrade your Contour deployment: 1814 1815 ```bash 1816 $ kubectl apply -f examples/contour/03-contour.yaml 1817 ``` 1818 1819 Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1820 1821 ```bash 1822 $ kubectl apply -f examples/contour/03-envoy.yaml 1823 ``` 1824 1825 ## Upgrading Contour 1.13.1 to 1.14.0 1826 1827 ### Required Envoy version 1828 1829 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.17.1`. 1830 1831 Please see the [Envoy Release Notes][29] for information about issues fixed in Envoy 1.17.1. 1832 1833 ### The easy way to upgrade 1834 1835 If the following are true for you: 1836 1837 * Your installation is in the `projectcontour` namespace. 1838 * You are using our [quickstart example][18] deployments. 1839 * Your cluster can take a few minutes of downtime. 1840 1841 Then the simplest way to upgrade to 1.14.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1842 1843 ```bash 1844 $ kubectl delete namespace projectcontour 1845 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.14.0/contour.yaml 1846 ``` 1847 1848 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1849 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1850 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1851 1852 ### The less easy way 1853 1854 This section contains information for administrators who wish to apply the Contour 1.13.1 to 1.14.0 changes manually. 1855 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.14.0` tag. 1856 1857 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 1858 1859 ```bash 1860 $ kubectl apply -f examples/contour/01-crds.yaml 1861 ``` 1862 1863 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1864 This will rotate the TLS certificates used for gRPC security. 1865 1866 ```bash 1867 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1868 ``` 1869 1870 If your version of Contour is older than v1.13, please upgrade to v1.13 first, then upgrade to v1.14.0. 1871 1872 This release includes an update to the Envoy service ports. Upgrade your Envoy service with the following: 1873 1874 ```bash 1875 $ kubectl apply -f examples/contour/02-service-envoy.yaml 1876 ``` 1877 1878 Upgrade your Contour deployment: 1879 1880 ```bash 1881 $ kubectl apply -f examples/contour/03-contour.yaml 1882 ``` 1883 1884 Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1885 1886 ```bash 1887 $ kubectl apply -f examples/contour/03-envoy.yaml 1888 ``` 1889 1890 ## Upgrading Contour 1.12.0 to 1.13.1 1891 1892 ### Required Envoy version 1893 1894 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.17.1`. 1895 1896 Please see the [Envoy Release Notes][29] for information about issues fixed in Envoy 1.17.1. 1897 1898 ### The easy way to upgrade 1899 1900 If the following are true for you: 1901 1902 * Your installation is in the `projectcontour` namespace. 1903 * You are using our [quickstart example][18] deployments. 1904 * Your cluster can take a few minutes of downtime. 1905 1906 Then the simplest way to upgrade to 1.13.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1907 1908 ```bash 1909 $ kubectl delete namespace projectcontour 1910 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.13.1/contour.yaml 1911 ``` 1912 1913 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1914 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1915 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1916 1917 ### The less easy way 1918 1919 This section contains information for administrators who wish to apply the Contour 1.12.0 to 1.13.1 changes manually. 1920 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.13.1` tag. 1921 1922 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 1923 1924 ```bash 1925 $ kubectl apply -f examples/contour/01-crds.yaml 1926 ``` 1927 1928 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1929 This will rotate the TLS certificates used for gRPC security. 1930 1931 ```bash 1932 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1933 ``` 1934 1935 If your version of Contour is older than v1.12, please upgrade to v1.12 first, then upgrade to v1.13.1. 1936 1937 Upgrade your Contour deployment: 1938 1939 ```bash 1940 $ kubectl apply -f examples/contour/03-contour.yaml 1941 ``` 1942 1943 Once the Contour deployment has finished upgrading, update the Envoy DaemonSet: 1944 1945 ```bash 1946 $ kubectl apply -f examples/contour/03-envoy.yaml 1947 ``` 1948 1949 ## Upgrading Contour 1.11.0 to 1.12.0 1950 1951 ### Required Envoy version 1952 1953 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.17.0`. 1954 1955 Please see the [Envoy Release Notes][28] for information about issues fixed in Envoy 1.17.0. 1956 1957 ### The easy way to upgrade 1958 1959 If the following are true for you: 1960 1961 * Your installation is in the `projectcontour` namespace. 1962 * You are using our [quickstart example][18] deployments. 1963 * Your cluster can take a few minutes of downtime. 1964 1965 Then the simplest way to upgrade to 1.12.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 1966 1967 ```bash 1968 $ kubectl delete namespace projectcontour 1969 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.12.0/contour.yaml 1970 ``` 1971 1972 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 1973 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 1974 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 1975 1976 ### The less easy way 1977 1978 This section contains information for administrators who wish to apply the Contour 1.11.0 to 1.12.0 changes manually. 1979 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.12.0` tag. 1980 1981 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 1982 1983 ```bash 1984 $ kubectl apply -f examples/contour/01-crds.yaml 1985 ``` 1986 1987 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 1988 This will rotate the TLS certificates used for gRPC security. 1989 1990 ```bash 1991 $ kubectl apply -f examples/contour/02-job-certgen.yaml 1992 ``` 1993 1994 If your version of Contour is older than v1.11, please upgrade to v1.11 first, then upgrade to v1.12. 1995 1996 Upgrade your Contour deployment: 1997 1998 ```bash 1999 $ kubectl apply -f examples/contour/03-contour.yaml 2000 ``` 2001 2002 Note that the Contour deployment needs to be updated before the Envoy daemon set since it contains backwards-compatible changes that are required in order to work with Envoy 1.17.0. 2003 Once the Contour deployment has finished upgrading, update the Envoy daemon set: 2004 2005 ```bash 2006 $ kubectl apply -f examples/contour/03-envoy.yaml 2007 ``` 2008 2009 ## Upgrading Contour 1.10.0 to 1.11.0 2010 2011 ### Required Envoy version 2012 2013 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.16.2`. 2014 2015 Please see the [Envoy Release Notes][27] for information about issues fixed in Envoy 1.16.2. 2016 2017 ### The easy way to upgrade 2018 2019 If the following are true for you: 2020 2021 * Your installation is in the `projectcontour` namespace. 2022 * You are using our [quickstart example][18] deployments. 2023 * Your cluster can take a few minutes of downtime. 2024 2025 Then the simplest way to upgrade to 1.11.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 2026 2027 ```bash 2028 $ kubectl delete namespace projectcontour 2029 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.11.0/contour.yaml 2030 ``` 2031 2032 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2033 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2034 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2035 2036 ### The less easy way 2037 2038 This section contains information for administrators who wish to apply the Contour 1.10.0 to 1.11.0 changes manually. 2039 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.11.0` tag. 2040 2041 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 2042 2043 ```bash 2044 $ kubectl apply -f examples/contour/01-crds.yaml 2045 ``` 2046 2047 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 2048 This will rotate the TLS certificates used for gRPC security. 2049 2050 ```bash 2051 $ kubectl apply -f examples/contour/02-job-certgen.yaml 2052 ``` 2053 2054 If your version of Contour is older than v1.10, please upgrade to v1.10 first, then upgrade to v1.11. 2055 For more information, see the [xDS Migration Guide][26]. 2056 2057 ```bash 2058 $ kubectl apply -f examples/contour/03-contour.yaml 2059 $ kubectl apply -f examples/contour/03-envoy.yaml 2060 ``` 2061 2062 ## Upgrading Contour 1.9.0 to 1.10.0 2063 2064 ### Required Envoy version 2065 2066 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.16.0`. 2067 2068 Please see the [Envoy Release Notes][25] for information about issues fixed in Envoy 1.16.0. 2069 2070 ### The easy way to upgrade 2071 2072 If the following are true for you: 2073 2074 * Your installation is in the `projectcontour` namespace. 2075 * You are using our [quickstart example][18] deployments. 2076 * Your cluster can take a few minutes of downtime. 2077 2078 Then the simplest way to upgrade to 1.10.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 2079 2080 ```bash 2081 $ kubectl delete namespace projectcontour 2082 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.10.0/contour.yaml 2083 ``` 2084 2085 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2086 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2087 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2088 2089 ### The less easy way 2090 2091 This section contains information for administrators who wish to apply the Contour 1.9.0 to 1.10.0 changes manually. 2092 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.10.0` tag. 2093 2094 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 2095 2096 ```bash 2097 $ kubectl apply -f examples/contour/01-crds.yaml 2098 ``` 2099 2100 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 2101 This will rotate the TLS certificates used for gRPC security. 2102 2103 ```bash 2104 $ kubectl apply -f examples/contour/02-job-certgen.yaml 2105 ``` 2106 2107 If your cluster cannot take downtime, it's important to first upgrade Contour to v1.10.0 then upgrade your Envoy pods. 2108 This is due to an Envoy xDS Resource API upgrade to `v3`. 2109 See the [xDS Migration Guide][26] for more information. 2110 2111 ```bash 2112 $ kubectl apply -f examples/contour/03-contour.yaml 2113 $ kubectl apply -f examples/contour/03-envoy.yaml 2114 ``` 2115 2116 ## Upgrading Contour 1.8.2 to 1.9.0 2117 2118 ### Required Envoy version 2119 2120 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.15.1`. 2121 2122 Please see the [Envoy Release Notes][23] for information about issues fixed in Envoy 1.15.1. 2123 2124 ### The easy way to upgrade 2125 2126 If the following are true for you: 2127 2128 * Your installation is in the `projectcontour` namespace. 2129 * You are using our [quickstart example][18] deployments. 2130 * Your cluster can take a few minutes of downtime. 2131 2132 Then the simplest way to upgrade to 1.9.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 2133 2134 ```bash 2135 $ kubectl delete namespace projectcontour 2136 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.9.0/contour.yaml 2137 ``` 2138 2139 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2140 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2141 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2142 2143 ### The less easy way 2144 2145 This section contains information for administrators who wish to apply the Contour 1.8.2 to 1.9.0 changes manually. 2146 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.9.0` tag. 2147 2148 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 2149 2150 ```bash 2151 $ kubectl apply -f examples/contour/01-crds.yaml 2152 ``` 2153 2154 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 2155 This will rotate the TLS certificates used for gRPC security. 2156 2157 ```bash 2158 $ kubectl apply -f examples/contour/02-job-certgen.yaml 2159 ``` 2160 2161 ### Removing the IngressRoute CRDs 2162 2163 As a reminder, support for `IngressRoute` was officially dropped in v1.6. 2164 If you haven't already migrated to `HTTPProxy`, see [the IngressRoute to HTTPProxy migration guide][24] for instructions on how to do so. 2165 Once you have migrated, delete the `IngressRoute` and related CRDs: 2166 2167 ```bash 2168 $ kubectl delete crd ingressroutes.contour.heptio.com 2169 $ kubectl delete crd tlscertificatedelegations.contour.heptio.com 2170 ``` 2171 2172 ## Upgrading Contour 1.7.0 to 1.8.0 2173 2174 ### Required Envoy version 2175 2176 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.15.0`. 2177 2178 Please see the [Envoy Release Notes][23] for information about issues fixed in Envoy 1.15.0. 2179 2180 ### The easy way to upgrade 2181 2182 If the following are true for you: 2183 2184 * Your installation is in the `projectcontour` namespace. 2185 * You are using our [quickstart example][18] deployments. 2186 * Your cluster can take a few minutes of downtime. 2187 2188 Then the simplest way to upgrade to 1.8.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 2189 2190 ```bash 2191 $ kubectl delete namespace projectcontour 2192 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.8.0/contour.yaml 2193 ``` 2194 2195 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2196 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2197 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2198 2199 ### The less easy way 2200 2201 This section contains information for administrators who wish to apply the Contour 1.7.0 to 1.8.0 changes manually. 2202 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.8.0` tag. 2203 2204 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 2205 2206 ```bash 2207 $ kubectl apply -f examples/contour/01-crds.yaml 2208 ``` 2209 2210 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. This will rotate the TLS certificates used for gRPC security. 2211 2212 2213 ```bash 2214 $ kubectl apply -f examples/contour/02-job-certgen.yaml 2215 ``` 2216 2217 ### Removing the IngressRoute CRDs 2218 2219 As a reminder, support for `IngressRoute` was officially dropped in v1.6. 2220 If you haven't already migrated to `HTTPProxy`, see [the IngressRoute to HTTPProxy migration guide][24] for instructions on how to do so. 2221 Once you have migrated, delete the `IngressRoute` and related CRDs: 2222 2223 ```bash 2224 $ kubectl delete crd ingressroutes.contour.heptio.com 2225 $ kubectl delete crd tlscertificatedelegations.contour.heptio.com 2226 ``` 2227 2228 ## Upgrading Contour 1.6.1 to 1.7.0 2229 2230 ### Required Envoy version 2231 2232 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.15.0`. 2233 2234 Please see the [Envoy Release Notes][23] for information about issues fixed in Envoy 1.15.0. 2235 2236 ### The easy way to upgrade 2237 2238 If the following are true for you: 2239 2240 * Your installation is in the `projectcontour` namespace. 2241 * You are using our [quickstart example][18] deployments. 2242 * Your cluster can take few minutes of downtime. 2243 2244 Then the simplest way to upgrade to 1.7.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 2245 2246 ```bash 2247 $ kubectl delete namespace projectcontour 2248 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.7.0/contour.yaml 2249 ``` 2250 2251 This will remove the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2252 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2253 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2254 2255 ### The less easy way 2256 2257 This section contains information for administrators who wish to apply the Contour 1.6.1 to 1.7.0 changes manually. 2258 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.7.0` tag. 2259 2260 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 2261 2262 ```bash 2263 $ kubectl apply -f examples/contour/01-crds.yaml 2264 ``` 2265 2266 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. This will rotate the TLS certs used for gRPC security. 2267 2268 2269 ```bash 2270 $ kubectl apply -f examples/contour/02-job-certgen.yaml 2271 ``` 2272 2273 To consume the new Secrets, reapply the Envoy Daemonset and the Contour Deployment YAML. 2274 All the Pods will gracefully restart and reconnect using the new TLS Secrets. 2275 After this, the gRPC session between Contour and Envoy can be re-keyed by regenerating the Secrets. 2276 2277 ```bash 2278 $ kubectl apply -f examples/contour/03-contour.yaml 2279 $ kubectl apply -f examples/contour/03-envoy.yaml 2280 ``` 2281 2282 ### Removing the IngressRoute CRDs 2283 2284 As a reminder, support for `IngressRoute` was officially dropped in v1.6. 2285 If you haven't already migrated to `HTTPProxy`, see [the IngressRoute to HTTPProxy migration guide][24] for instructions on how to do so. 2286 Once you have migrated, delete the `IngressRoute` and related CRDs: 2287 2288 ```bash 2289 $ kubectl delete crd ingressroutes.contour.heptio.com 2290 $ kubectl delete crd tlscertificatedelegations.contour.heptio.com 2291 ``` 2292 2293 ## Upgrading Contour 1.5.1 to 1.6.1 2294 2295 ### Required Envoy version 2296 2297 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.14.3`. 2298 2299 Please see the [Envoy Release Notes][22] for information about issues fixed in Envoy 1.14.3. 2300 2301 ### The easy way to upgrade 2302 2303 If the following are true for you: 2304 2305 * Your installation is in the `projectcontour` namespace. 2306 * You are using our [quickstart example][18] deployments. 2307 * Your cluster can take few minutes of downtime. 2308 2309 Then the simplest way to upgrade to 1.6.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 2310 2311 ```bash 2312 $ kubectl delete crd ingressroutes.contour.heptio.com 2313 $ kubectl delete crd tlscertificatedelegations.contour.heptio.com 2314 $ kubectl delete namespace projectcontour 2315 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.6.1/contour.yaml 2316 ``` 2317 2318 This will remove the IngressRoute CRD, and both the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2319 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2320 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2321 2322 ### The less easy way 2323 2324 This section contains information for administrators who wish to apply the Contour 1.5.1 to 1.6.1 changes manually. 2325 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.6.1` tag. 2326 2327 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 2328 2329 ```bash 2330 $ kubectl apply -f examples/contour/01-crds.yaml 2331 ``` 2332 2333 Administrators should also remove the IngressRoute CRDs: 2334 ```bash 2335 $ kubectl delete crd ingressroutes.contour.heptio.com 2336 $ kubectl delete crd tlscertificatedelegations.contour.heptio.com 2337 ``` 2338 2339 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. This will rotate the TLS certs used for gRPC security. 2340 2341 2342 ```bash 2343 $ kubectl apply -f examples/contour/02-job-certgen.yaml 2344 ``` 2345 2346 To consume the new Secrets, reapply the Envoy Daemonset and the Contour Deployment YAML. 2347 All the Pods will gracefully restart and reconnect using the new TLS Secrets. 2348 After this, the gRPC session between Contour and Envoy can be re-keyed by regenerating the Secrets. 2349 2350 ```bash 2351 $ kubectl apply -f examples/contour/03-contour.yaml 2352 $ kubectl apply -f examples/contour/03-envoy.yaml 2353 ``` 2354 2355 If you are upgrading from Contour 1.6.0, the only required change is to upgrade the version of the Envoy image version from `v1.14.2` to `v1.14.3`. 2356 The Contour image can optionally be upgraded to `v1.6.1`. 2357 2358 2359 ## Upgrading Contour 1.4.0 to 1.5.1 2360 2361 ### Required Envoy version 2362 2363 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.14.2`. 2364 2365 Please see the [Envoy Release Notes][21] for information about issues fixed in Envoy 1.14.2. 2366 2367 ### The easy way to upgrade 2368 2369 If the following are true for you: 2370 2371 * Your installation is in the `projectcontour` namespace. 2372 * You are using our [quickstart example][18] deployments. 2373 * Your cluster can take few minutes of downtime. 2374 2375 Then the simplest way to upgrade to 1.5.1 is to delete the `projectcontour` namespace and reapply one of the example configurations: 2376 2377 ```bash 2378 $ kubectl delete namespace projectcontour 2379 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.5.1/contour.yaml 2380 ``` 2381 2382 This will remove both the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2383 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2384 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2385 2386 ### The less easy way 2387 2388 This section contains information for administrators who wish to apply the Contour 1.4.0 to 1.5.1 changes manually. 2389 The YAML files referenced in this section can be found by cloning the Contour repository and checking out the `v1.5.1` tag. 2390 2391 The Contour CRD definition must be re-applied to the cluster, since a number of compatible changes and additions have been made to the Contour API: 2392 2393 ```bash 2394 $ kubectl apply -f examples/contour/01-crds.yaml 2395 ``` 2396 2397 In this release, the format of the TLS Secrets that are used to secure the gRPC session between Envoy and Contour has changed. 2398 This means that the Envoy Daemonset and the Contour Deployment have been changed to mount the TLS secrets volume differently. 2399 Users of the example deployment should first reapply the certgen Job YAML which will re-generate the relevant Secrets in the new format, which is compatible with [cert-manager](https://cert-manager.io) TLS secrets. 2400 2401 2402 ```bash 2403 $ kubectl apply -f examples/contour/02-job-certgen.yaml 2404 ``` 2405 2406 To consume the new Secrets, reapply the Envoy Daemonset and the Contour Deployment YAML. 2407 All the Pods will gracefully restart and reconnect using the new TLS Secrets. 2408 After this, the gRPC session between Contour and Envoy can be re-keyed by regenerating the Secrets. 2409 2410 ```bash 2411 $ kubectl apply -f examples/contour/03-contour.yaml 2412 $ kubectl apply -f examples/contour/03-envoy.yaml 2413 ``` 2414 2415 Users who secure the gRPC session with their own certificate may need to modify the Envoy Daemonset and the Contour Deployment to ensure that their Secrets are correctly mounted within the corresponding Pod containers. 2416 When making these changes, be sure to retain the `--resources-dir` flag to the `contour bootstrap` command so that Envoy will be configured with reloadable TLS certificate support. 2417 2418 ## Upgrading Contour 1.3.0 to 1.4.0 2419 2420 ### Required Envoy version 2421 2422 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.14.1`. 2423 2424 Please see the [Envoy Release Notes][20] for information about issues fixed in Envoy 1.14.1. 2425 2426 ### The easy way to upgrade 2427 2428 If the following are true for you: 2429 2430 * Your installation is in the `projectcontour` namespace. 2431 * You are using our [quickstart example][18] deployments. 2432 * Your cluster can take few minutes of downtime. 2433 2434 Then the simplest way to upgrade to 1.4.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 2435 2436 ```bash 2437 $ kubectl delete namespace projectcontour 2438 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.4.0/contour.yaml 2439 ``` 2440 2441 This will remove both the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2442 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2443 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2444 2445 **Note:** If you deployed Contour into a different namespace than `projectcontour` with a standard example, please delete that namespace. 2446 Then in your editor of choice do a search and replace for `projectcontour` and replace it with your preferred name space and apply the updated manifest. 2447 2448 ### The less easy way 2449 2450 This section contains information for administrators who wish to apply the Contour 1.3.0 to 1.4.0 changes manually. 2451 2452 #### Upgrade to Contour 1.4.0 2453 2454 Change the Contour image version to `docker.io/projectcontour/contour:v1.4.0` 2455 2456 Because there has been a change to Envoy to add a serviceaccount, you need to reapply the Contour CRDs and RBAC. 2457 2458 From within a clone of the repo, checkout `release-1.4`, then you can: 2459 2460 ```bash 2461 kubectl apply -f examples/contour/00-common.yaml 2462 kubectl apply -f examples/contour/01-crds.yaml 2463 kubectl apply -f examples/contour/02-rbac.yaml 2464 ``` 2465 2466 If you are using our Envoy daemonset: 2467 2468 ```bash 2469 kubectl apply -f examples/contour/03-envoy.yaml 2470 ``` 2471 2472 Otherwise, you should add the new `envoy` `serviceAccount` to your Envoy deployment. 2473 This will be used in the future to add further container-level security via PodSecurityPolicies. 2474 2475 ## Upgrading Contour 1.2.1 to 1.3.0 2476 2477 ### Required Envoy version 2478 2479 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.13.1`. 2480 2481 Please see the [Envoy Release Notes][17] for information about issues fixed in Envoy 1.13.1. 2482 2483 ### The easy way to upgrade 2484 2485 If the following are true for you: 2486 2487 * Your installation is in the `projectcontour` namespace. 2488 * You are using our [quickstart example][18] deployments. 2489 * Your cluster can take few minutes of downtime. 2490 2491 Then the simplest way to upgrade to 1.3.0 is to delete the `projectcontour` namespace and reapply one of the example configurations: 2492 2493 ```bash 2494 $ kubectl delete namespace projectcontour 2495 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.3.0/contour.yaml 2496 ``` 2497 2498 This will remove both the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2499 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2500 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2501 2502 **Note:** If you deployed Contour into a different namespace than `projectcontour` with a standard example, please delete that namespace. 2503 Then in your editor of choice do a search and replace for `projectcontour` and replace it with your preferred name space and apply the updated manifest. 2504 2505 ### The less easy way 2506 2507 This section contains information for administrators who wish to apply the Contour 1.2.1 to 1.3.0 changes manually. 2508 2509 #### Upgrade to Contour 1.3.0 2510 2511 Change the Contour image version to `docker.io/projectcontour/contour:v1.3.0` 2512 2513 ## Upgrading Contour 1.2.0 to 1.2.1 2514 2515 ### Required Envoy version 2516 2517 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.13.1`. 2518 2519 Please see the [Envoy Release Notes][17] for information about issues fixed in Envoy 1.13.1. 2520 2521 ### The easy way to upgrade 2522 2523 If the following are true for you: 2524 2525 * Your installation is in the `projectcontour` namespace. 2526 * You are using our [quickstart example][18] deployments. 2527 * Your cluster can take few minutes of downtime. 2528 2529 Then the simplest way to upgrade to 1.2.1 is to delete the `projectcontour` namespace and reapply one of the example configurations. 2530 From the root directory of the repository: 2531 2532 ```bash 2533 $ kubectl delete namespace projectcontour 2534 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.2.1/contour.yaml 2535 ``` 2536 2537 This will remove both the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2538 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2539 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2540 2541 **Note:** If you deployed Contour into a different namespace than `projectcontour` with a standard example, please delete that namespace. 2542 Then in your editor of choice do a search and replace for `projectcontour` and replace it with your preferred name space and apply the updated manifest. 2543 2544 ### The less easy way 2545 2546 This section contains information for administrators who wish to apply the Contour 1.2.0 to 1.2.1 changes manually. 2547 2548 #### Upgrade to Contour 1.2.1 2549 2550 Change the Contour image version to `docker.io/projectcontour/contour:v1.2.1`. 2551 2552 #### Upgrade to Envoy 1.13.1 2553 2554 Contour 1.2.1 requires Envoy 1.13.1. 2555 Change the Envoy image version to `docker.io/envoyproxy/envoy:v1.13.1`. 2556 2557 _Note: Envoy 1.13.1 includes fixes to a number of [CVEs][19]_ 2558 2559 ## Upgrading Contour 1.1.0 to 1.2.1 2560 2561 ### Required Envoy version 2562 2563 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.13.1`. 2564 2565 Please see the [Envoy Release Notes][17] for information about issues fixed in Envoy 1.13.1. 2566 2567 ### The easy way to upgrade 2568 2569 If the following are true for you: 2570 2571 * Your installation is in the `projectcontour` namespace. 2572 * You are using our [quickstart example][18] deployments. 2573 * Your cluster can take few minutes of downtime. 2574 2575 Then the simplest way to upgrade to 1.2.1 is to delete the `projectcontour` namespace and reapply one of the example configurations. 2576 From the root directory of the repository: 2577 2578 ```bash 2579 $ kubectl delete namespace projectcontour 2580 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.2.1/contour.yaml 2581 ``` 2582 2583 This will remove both the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2584 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2585 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2586 2587 **Note:** If you deployed Contour into a different namespace than `projectcontour` with a standard example, please delete that namespace. 2588 Then in your editor of choice do a search and replace for `projectcontour` and replace it with your preferred name space and apply the updated manifest. 2589 2590 ### The less easy way 2591 2592 This section contains information for administrators who wish to apply the Contour 1.1.0 to 1.2.1 changes manually. 2593 2594 #### Upgrade to Contour 1.2.1 2595 2596 Change the Contour image version to `docker.io/projectcontour/contour:v1.2.1`. 2597 2598 #### Upgrade to Envoy 1.13.1 2599 2600 Contour 1.2.1 requires Envoy 1.13.1. 2601 Change the Envoy image version to `docker.io/envoyproxy/envoy:v1.13.0`. 2602 2603 #### Envoy shutdown manager 2604 2605 Contour 1.2.1 introduces a new sidecar to aid graceful shutdown of the Envoy pod. 2606 Consult [shutdown manager]({% link docs/v1.2.1/redeploy-envoy.md %}) documentation for installation instructions. 2607 2608 ## Upgrading Contour 1.0.1 to 1.1.0 2609 2610 ### Required Envoy version 2611 2612 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.12.2`. 2613 2614 Please see the [Envoy Release Notes][15] for information about issues fixed in Envoy 1.12.2. 2615 2616 ### The easy way to upgrade 2617 2618 If the following are true for you: 2619 2620 * Your installation is in the `projectcontour` namespace. 2621 * You are using one of the [example][1] deployments. 2622 * Your cluster can take few minutes of downtime. 2623 2624 Then the simplest way to upgrade to 1.1.0 is to delete the `projectcontour` namespace and reapply one of the example configurations. 2625 From the root directory of the repository: 2626 2627 ```bash 2628 $ kubectl delete namespace projectcontour 2629 $ kubectl apply -f examples/<your-desired-deployment> 2630 ``` 2631 2632 This will remove both the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2633 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2634 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2635 2636 **Note:** If you deployed Contour into a different namespace than `projectcontour` with a standard example, please delete that namespace. 2637 Then in your editor of choice do a search and replace for `projectcontour` and replace it with your preferred name space and apply the updated manifest. 2638 2639 **Note:** If you are deploying to a cluster where you have previously installed alpha versions of the Contour API, applying the Contour CRDs in `examples/contour` may fail with a message similar to `Invalid value: "v1alpha1": must appear in spec.versions`. In this case, you need to delete the old CRDs and apply the new ones. 2640 2641 ```bash 2642 $ kubectl delete namespace projectcontour 2643 $ kubectl get crd | awk '/projectcontour.io|contour.heptio.com/{print $1}' | xargs kubectl delete crd 2644 $ kubectl apply -f examples/<your-desired-deployment> 2645 ``` 2646 2647 ### The less easy way 2648 2649 This section contains information for administrators who wish to apply the Contour 1.0.1 to 1.1.0 changes manually. 2650 2651 #### Upgrade to Contour 1.1.0 2652 2653 Change the Contour image version to `docker.io/projectcontour/contour:v1.1.0`. 2654 2655 #### Upgrade to Envoy 1.12.2 2656 2657 Contour 1.1.0 requires Envoy 1.12.2. Change the Envoy image version to `docker.io/envoyproxy/envoy:v1.12.2`. 2658 2659 ## Upgrading Contour 1.0.0 to 1.0.1 2660 2661 ### The easy way to upgrade 2662 2663 If you are running Contour 1.0.0, the easy way to upgrade to Contour 1.0.1 is to reapply the [quickstart yaml][16]. 2664 2665 ```bash 2666 $ kubectl apply -f {{< param base_url >}}/quickstart/v1.0.1/contour.yaml 2667 ``` 2668 2669 ### The less easy way 2670 2671 This section contains information for administrators who wish to manually upgrade from Contour 1.0.0 to Contour 1.0.1. 2672 2673 #### Contour version 2674 2675 Ensure the Contour image version is `docker.io/projectcontour/contour:v1.0.1`. 2676 2677 #### Envoy version 2678 2679 Ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.12.2`. 2680 2681 Please see the [Envoy Release Notes][15] for information about issues fixed in Envoy 1.12.2. 2682 2683 ## Upgrading Contour 0.15.3 to 1.0.0 2684 2685 ### Required Envoy version 2686 2687 The required version of Envoy remains unchanged. 2688 Ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.11.2`. 2689 2690 ### The easy way to upgrade 2691 2692 If the following are true for you: 2693 2694 * Your previous installation is in the `projectcontour` namespace. 2695 * You are using one of the [example][2] deployments. 2696 * Your cluster can take few minutes of downtime. 2697 2698 Then the simplest way to upgrade is to delete the `projectcontour` namespace and reapply the `examples/contour` sample manifest. 2699 From the root directory of the repository: 2700 2701 ```bash 2702 $ kubectl delete namespace projectcontour 2703 $ kubectl apply -f examples/contour 2704 ``` 2705 2706 This will remove both the Envoy and Contour pods from your cluster and recreate them with the updated configuration. 2707 If you're using a `LoadBalancer` Service, deleting and recreating may change the public IP assigned by your cloud provider. 2708 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2709 2710 ### The less easy way 2711 2712 This section contains information for administrators who wish to manually upgrade from Contour 0.15.3 to Contour 1.0.0. 2713 2714 #### Upgrade to Contour 1.0.0 2715 2716 Change the Contour image version to `docker.io/projectcontour/contour:v1.0.0`. 2717 2718 Note that as part of sunsetting the Heptio brand, Contour Docker images have moved from `gcr.io/heptio-images` to `docker.io/projectcontour`. 2719 2720 #### Reapply HTTPProxy and IngressRoute CRD definitions 2721 2722 Contour 1.0.0 ships with updated OpenAPIv3 validation schemas. 2723 2724 Contour 1.0.0 promotes the HTTPProxy CRD to v1. 2725 HTTPProxy is now considered stable, and there will only be additive, compatible changes in the future. 2726 See the [HTTPProxy documentation][3] for more information. 2727 2728 ```bash 2729 $ kubectl apply -f examples/contour/01-crds.yaml 2730 ``` 2731 2732 #### Update deprecated `contour.heptio.com` annotations 2733 2734 All the annotations with the prefix `contour.heptio.com` have been migrated to their respective `projectcontour.io` counterparts. 2735 The deprecated `contour.heptio.com` annotations will be recognized through the Contour 1.0 release, but are scheduled to be removed after Contour 1.0. 2736 2737 See the [annotation documentation][4] for more information. 2738 2739 #### Update old `projectcontour.io/v1alpha1` group versions 2740 2741 If you are upgrading a cluster that you previously installed a 1.0.0 release candidate, note that Contour 1.0.0 moves the HTTPProxy CRD from `projectcontour.io/v1alpha1` to `projectcontour.io/v1` and will no longer recognize the former group version. 2742 2743 Please edit your HTTPProxy documents to update their group version to `projectcontour.io/v1`. 2744 2745 #### Check for HTTPProxy v1 schema changes 2746 2747 As part of finalizing the HTTPProxy v1 schema, three breaking changes have been introduced. 2748 If you are upgrading a cluster that you previously installed a Contour 1.0.0 release candidate, you may need to edit HTTPProxy object to conform to the upgraded schema. 2749 2750 * The per-route prefix rewrite key, `prefixRewrite` has been removed. 2751 See [#899][5] for the status of its replacement. 2752 2753 * The per-service health check key, `healthcheck` has moved to per-route and has been renamed `healthCheckPolicy`. 2754 2755 <table class="table table-borderless" style="border: none;"> 2756 <tr><th>Before:</th><th>After:</th></tr> 2757 2758 <tr> 2759 <td><pre><code class="language-yaml" data-lang="yaml"> 2760 spec: 2761 routes: 2762 - conditions: 2763 - prefix: / 2764 services: 2765 - name: www 2766 port: 80 2767 healthcheck: 2768 - path: /healthy 2769 intervalSeconds: 5 2770 timeoutSeconds: 2 2771 unhealthyThresholdCount: 3 2772 healthyThresholdCount: 5 2773 </code></pre></td> 2774 2775 <td> 2776 <pre><code class="language-yaml" data-lang="yaml"> 2777 spec: 2778 routes: 2779 - conditions: 2780 - prefix: / 2781 healthCheckPolicy: 2782 - path: /healthy 2783 intervalSeconds: 5 2784 timeoutSeconds: 2 2785 unhealthyThresholdCount: 3 2786 healthyThresholdCount: 5 2787 services: 2788 - name: www 2789 port: 80 2790 </code></pre></td> 2791 2792 </tr> 2793 </table> 2794 2795 * The per-service load balancer strategy key, `strategy` has moved to per-route and has been renamed `loadBalancerPolicy`. 2796 2797 <table class="table table-borderless" style="border: none;"> 2798 <tr><th>Before:</th><th>After:</th></tr> 2799 2800 <tr> 2801 <td><pre><code class="language-yaml" data-lang="yaml"> 2802 spec: 2803 routes: 2804 - conditions: 2805 - prefix: / 2806 services: 2807 - name: www 2808 port: 80 2809 strategy: WeightedLeastRequest 2810 </code></pre></td> 2811 2812 <td><pre><code class="language-yaml" data-lang="yaml"> 2813 spec: 2814 routes: 2815 - conditions: 2816 - prefix: / 2817 loadBalancerPolicy: 2818 strategy: WeightedLeastRequest 2819 services: 2820 - name: www 2821 port: 80 2822 </code></pre></td> 2823 2824 </tr> 2825 </table> 2826 2827 ##### Check for Contour namespace change 2828 2829 As part of sunsetting the Heptio brand the `heptio-contour` namespace has been renamed to `projectcontour`. 2830 Contour assumes it will be deployed into the `projectcontour` namespace. 2831 2832 If you deploy Contour into a different namespace you will need to pass `contour bootstrap --namespace=<namespace>` and update the leader election parameters in the [`contour.yaml` configuration][6] 2833 as appropriate. 2834 2835 #### Split deployment/daemonset now the default 2836 2837 We have changed the example installation to use a separate pod installation, where Contour is in a Deployment and Envoy is in a Daemonset. 2838 Separated pod installations separate the lifecycle of Contour and Envoy, increasing operability. 2839 Because of this, we are marking the single pod install type as officially deprecated. 2840 If you are still running a single pod install type, please review the [`contour` example][7] and either adapt it or use it directly. 2841 2842 #### Verify leader election 2843 2844 Contour 1.0.0 enables leader election by default. 2845 No specific configuration is required if you are using the [example deployment][7]. 2846 2847 Leader election requires that Contour have write access to a ConfigMap 2848 called `leader-elect` in the project-contour namespace. 2849 This is done with the [contour-leaderelection Role][8] in the [example RBAC][9]. 2850 The namespace and name of the configmap are configurable via the configuration file. 2851 2852 The leader election mechanism no longer blocks serving of gRPC until an instance becomes the leader. 2853 Leader election controls writing status back to Contour CRDs (like HTTPProxy and IngressRoute) so that only one Contour pod writes status at a time. 2854 2855 Should you wish to disable leader election, pass `contour serve --disable-leader-election`. 2856 2857 #### Envoy pod readiness checks 2858 2859 Update the readiness checks on your Envoy pod's spec to reflect Envoy 1.11.1's `/ready` endpoint 2860 ```yaml 2861 readinessProbe: 2862 httpGet: 2863 path: /ready 2864 port: 8002 2865 ``` 2866 2867 #### Root namespace restriction 2868 2869 The `contour serve --ingressroute-root-namespaces` flag has been renamed to `--root-namespaces`. 2870 If you use this feature please update your deployments. 2871 2872 ## Upgrading Contour 0.14.x to 0.15.3 2873 2874 Contour 0.15.3 requires changes to your deployment manifests to explicitly opt in, or opt out of, secure communication between Contour and Envoy. 2875 2876 Contour 0.15.3 also adds experimental support for leader election which may be useful for installations which have split their Contour and Envoy containers into separate pods. 2877 A configuration we call _split deployment_. 2878 2879 ### Breaking change 2880 2881 Contour's `contour serve` now requires that either TLS certificates be available, or you supply the `--insecure` parameter. 2882 2883 **If you do not supply TLS details or `--insecure`, `contour serve` will not start.** 2884 2885 ### Recommended Envoy version 2886 2887 All users should ensure the Envoy image version is `docker.io/envoyproxy/envoy:v1.11.2`. 2888 2889 Please see the [Envoy Release Notes][10] for information about issues fixed in Envoy 1.11.2. 2890 2891 ### The easy way to upgrade 2892 2893 If the following are true for you: 2894 2895 * Your installation is in the `heptio-contour` namespace. 2896 * You are using one of the [example][11] deployments. 2897 * Your cluster can take few minutes of downtime. 2898 2899 Then the simplest way to upgrade to 0.15.3 is to delete the `heptio-contour` namespace and reapply one of the example configurations. 2900 From the root directory of the repository: 2901 2902 ```bash 2903 $ kubectl delete namespace heptio-contour 2904 $ kubectl apply -f examples/<your-desired-deployment> 2905 ``` 2906 2907 If you're using a `LoadBalancer` Service, (which most of the examples do) deleting and recreating may change the public IP assigned by your cloud provider. 2908 You'll need to re-check where your DNS names are pointing as well, using [Get your hostname or IP address][12]. 2909 2910 **Note:** If you deployed Contour into a different namespace than heptio-contour with a standard example, please delete that namespace. 2911 Then in your editor of choice do a search and replace for `heptio-contour` and replace it with your preferred name space and apply the updated manifest. 2912 2913 ### The less easy way 2914 2915 This section contains information for administrators who wish to apply the Contour 0.14.x to 0.15.3 changes manually. 2916 2917 #### Upgrade to Contour 0.15.3 2918 2919 Due to the sun setting on the Heptio brand, from v0.15.0 onwards our images are now served from the docker hub repository [`docker.io/projectcontour/contour`][13] 2920 2921 Change the Contour image version to `docker.io/projectcontour/contour:v0.15.3`. 2922 2923 #### Enabling TLS for gRPC 2924 2925 You *must* either enable TLS for gRPC serving, or put `--insecure` into your `contour serve` startup line. 2926 If you are running with both Contour and Envoy in a single pod, the existing deployment examples have already been updated with this change. 2927 2928 If you are running using the `ds-hostnet-split` example or a derivative, we strongly recommend that you generate new certificates for securing your gRPC communication between Contour and Envoy. 2929 2930 There is a Job in the `ds-hostnet-split` directory that will use the new `contour certgen` command to generate a CA and then sign Contour and Envoy keypairs, which can also then be saved directly to Kubernetes as Secrets, ready to be mounted into your Contour and Envoy Deployments and Daemonsets. 2931 2932 If you would like more detail, see [grpc-tls-howto.md][14], which explains your options. 2933 2934 #### Upgrade to Envoy 1.11.2 2935 2936 Contour 0.15.3 requires Envoy 1.11.2. Change the Envoy image version to `docker.io/envoyproxy/envoy:v1.11.2`. 2937 2938 #### Enabling Leader Election 2939 2940 Contour 0.15.3 adds experimental support for leader election. 2941 Enabling leader election will mean that only one of the Contour pods will actually serve gRPC traffic. 2942 This will ensure that all Envoy's take their configuration from the same Contour. 2943 You can enable leader election with the `--enable-leader-election` flag to `contour serve`. 2944 2945 If you have deployed Contour and Envoy in their own pods--we call this split deployment--you should enable leader election so all envoy pods take their configuration from the lead contour. 2946 2947 To enable leader election, the following must be true for you: 2948 2949 - You are running in a split Contour and Envoy setup. 2950 That is, there are separate Contour and Envoy pod(s). 2951 2952 In order for leader election to work, you must make the following changes to your setup: 2953 2954 - The Contour Deployment must have its readiness probe changed too TCP readiness probe configured to check port 8001 (the gRPC port), as non-leaders will not serve gRPC, and Envoys may not be properly configured if they attempt to connect to a non-leader Contour. 2955 That is, you will need to change: 2956 2957 ```yaml 2958 readinessProbe: 2959 httpGet: 2960 path: /healthz 2961 port: 8000 2962 ``` 2963 to 2964 2965 ```yaml 2966 readinessProbe: 2967 tcpSocket: 2968 port: 8001 2969 initialDelaySeconds: 15 2970 periodSeconds: 10 2971 ``` 2972 inside the Pod spec. 2973 - The update strategy for the Contour deployment must be changed to `Recreate` instead of `RollingUpdate`, as pods will never become Ready (since they won't pass the readiness probe). 2974 Add 2975 2976 ```yaml 2977 strategy: 2978 type: Recreate 2979 ``` 2980 to the top level of the Pod spec. 2981 - Leader election is currently hard-coded to use a ConfigMap named `contour` in this namespace for the leader election lock. 2982 If you are using a newer installation of Contour, this may be present already, if not, the leader election library will create an empty ConfigMap for you. 2983 2984 Once these changes are made, add `--enable-leader-election` to your `contour serve` command. 2985 The leader will perform and log its operations as normal, and the non-leaders will block waiting to become leader. 2986 You can inspect the state of the leadership using 2987 2988 ```bash 2989 $ kubectl describe configmap -n heptio-contour contour 2990 ``` 2991 2992 and checking the annotations that store exact details using 2993 2994 ```bash 2995 $ kubectl get configmap -n heptio-contour -o yaml contour 2996 ``` 2997 2998 [1]: https://github.com/projectcontour/contour/tree/main/examples/contour 2999 [2]: https://github.com/projectcontour/contour/blob/v1.0.0/examples 3000 [3]: /docs/main/config/fundamentals 3001 [4]: /docs/main/config/annotations 3002 [5]: https://github.com/projectcontour/contour/issues/899 3003 [6]: /docs/main/configuration 3004 [7]: https://github.com/projectcontour/contour/blob/main/examples/contour/README.md 3005 [8]: https://github.com/projectcontour/contour/blob/v1.0.0/examples/contour/02-rbac.yaml#L71 3006 [9]: https://github.com/projectcontour/contour/blob/main/examples/contour/02-rbac.yaml 3007 [10]: https://www.envoyproxy.io/docs/envoy/v1.11.2/intro/version_history 3008 [11]: https://github.com/projectcontour/contour/blob/v0.15.3/examples/ 3009 [12]: /docs/main/deploy-options 3010 [13]: https://hub.docker.com/r/projectcontour/contour 3011 [14]: /docs/main/grpc-tls-howto 3012 [15]: https://www.envoyproxy.io/docs/envoy/v1.12.2/intro/version_history 3013 [16]: /getting-started 3014 [17]: https://www.envoyproxy.io/docs/envoy/v1.13.1/intro/version_history 3015 [18]: https://projectcontour.io/quickstart/main/contour.yaml 3016 [19]: https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/envoy-announce/sVqmxy0un2s/8aq430xiHAAJ 3017 [20]: https://www.envoyproxy.io/docs/envoy/v1.14.1/intro/version_history 3018 [21]: https://www.envoyproxy.io/docs/envoy/v1.14.2/intro/version_history 3019 [22]: https://www.envoyproxy.io/docs/envoy/v1.14.3/intro/version_history 3020 [23]: https://www.envoyproxy.io/docs/envoy/v1.15.0/version_history/current 3021 [24]: /guides/ingressroute-to-httpproxy/ 3022 [25]: https://www.envoyproxy.io/docs/envoy/v1.16.0/version_history/current 3023 [26]: /guides/xds-migration 3024 [27]: https://www.envoyproxy.io/docs/envoy/v1.16.2/version_history/current 3025 [28]: https://www.envoyproxy.io/docs/envoy/v1.17.0/version_history/current 3026 [29]: https://www.envoyproxy.io/docs/envoy/v1.17.1/version_history/current 3027 [30]: https://www.envoyproxy.io/docs/envoy/v1.17.2/version_history/current 3028 [31]: https://www.envoyproxy.io/docs/envoy/v1.18.2/version_history/current 3029 [32]: https://www.envoyproxy.io/docs/envoy/v1.18.3/version_history/current 3030 [33]: https://www.envoyproxy.io/docs/envoy/v1.19.0/version_history/current 3031 [34]: https://www.envoyproxy.io/docs/envoy/v1.19.1/version_history/current 3032 [35]: https://www.envoyproxy.io/docs/envoy/v1.21.0/version_history/current 3033 [36]: https://www.envoyproxy.io/docs/envoy/v1.21.1/version_history/current 3034 [37]: https://www.envoyproxy.io/docs/envoy/v1.22.0/version_history/current 3035 [38]: https://www.envoyproxy.io/docs/envoy/v1.22.2/version_history/current 3036 [39]: https://www.envoyproxy.io/docs/envoy/v1.21.3/version_history/current 3037 [40]: https://www.envoyproxy.io/docs/envoy/v1.23.0/version_history/v1.23/v1.23.0 3038 [41]: https://www.envoyproxy.io/docs/envoy/v1.23.1/version_history/v1.23/v1.23.1 3039 [42]: https://www.envoyproxy.io/docs/envoy/v1.24.0/version_history/v1.24/v1.24.0 3040 [43]: https://www.envoyproxy.io/docs/envoy/v1.22.6/version_history/current 3041 [44]: https://www.envoyproxy.io/docs/envoy/v1.23.3/version_history/v1.23/v1.23.3 3042 [45]: https://www.envoyproxy.io/docs/envoy/v1.24.1/version_history/v1.24/v1.24.1 3043 [46]: https://www.envoyproxy.io/docs/envoy/v1.25.0/version_history/v1.25/v1.25.0