istio.io/istio@v0.0.0-20240520182934-d79c90f27776/samples/helloworld/README.md (about)

     1  # Helloworld service
     2  
     3  This sample includes two versions of a simple helloworld service that returns its version
     4  and instance (hostname) when called.
     5  It can be used as a test service when experimenting with version routing.
     6  
     7  This service is also used to demonstrate canary deployments working in conjunction with autoscaling.
     8  See [Canary deployments using Istio](https://istio.io/blog/2017/0.1-canary).
     9  
    10  ## Start the helloworld service
    11  
    12  The following commands assume you have
    13  [automatic sidecar injection](https://istio.io/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection)
    14  enabled in your cluster.
    15  If not, you'll need to modify them to include
    16  [manual sidecar injection](https://istio.io/docs/setup/additional-setup/sidecar-injection/#manual-sidecar-injection).
    17  
    18  To run both versions of the helloworld service, use the following command:
    19  
    20  ```bash
    21  kubectl apply -f helloworld.yaml
    22  ```
    23  
    24  Alternatively, you can run just one version at a time by first defining the service:
    25  
    26  ```bash
    27  kubectl apply -f helloworld.yaml -l service=helloworld
    28  ```
    29  
    30  and then deploying version v1, v2, or both:
    31  
    32  ```bash
    33  kubectl apply -f helloworld.yaml -l version=v1
    34  kubectl apply -f helloworld.yaml -l version=v2
    35  ```
    36  
    37  For even more flexibility, there is also a script, `gen-helloworld.sh`, that will
    38  generate YAML for the helloworld service. This script takes the following
    39  arguments:
    40  
    41  | Argument              | Default | Description                                                            |
    42  |-----------------------|---------|------------------------------------------------------------------------|
    43  | `-h`,`--help`         |         | Prints usage information.                                              |
    44  | `--version`           | `v1`    | Specifies the version that will be returned by the helloworld service. |
    45  | `--includeService`    | `true`  | If `true` the service will be included in the YAML.                    |
    46  | `--includeDeployment` | `true`  | If `true` the deployment will be included in the YAML.                 |
    47  
    48  You can use this script to deploy a custom version:
    49  
    50  ```bash
    51  ./gen-helloworld.sh --version customversion | \
    52      kubectl apply -f -
    53  ```
    54  
    55  ## Configure the helloworld gateway
    56  
    57  *___Note:___ Istio intends to make the Kubernetes [Gateway API](https://gateway-api.sigs.k8s.io/) the default API for traffic management [in the future](https://istio.io/latest/blog/2022/gateway-api-beta/). You can use the Gateway API to configure the helloworld service, instead of the classic Istio configuration model, by following the instructions in [./gateway-api/README.md](./gateway-api/README.md), instead of the instructions below.*
    58  
    59  Apply the helloworld gateway configuration:
    60  
    61  ```bash
    62  kubectl apply -f helloworld-gateway.yaml
    63  ```
    64  
    65  Follow [these instructions](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports)
    66  to set the INGRESS_HOST and INGRESS_PORT variables and then confirm the sample is running using curl:
    67  
    68  ```bash
    69  export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT
    70  curl http://$GATEWAY_URL/hello
    71  ```
    72  
    73  ## Autoscale the services
    74  
    75  Note that a Kubernetes [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)
    76  only works if all containers in the pods request cpu. In this sample the deployment
    77  containers in `helloworld.yaml` are configured with the request.
    78  The injected istio-proxy containers also include cpu requests,
    79  making the helloworld service ready for autoscaling.
    80  
    81  Enable autoscaling on both versions of the service:
    82  
    83  ```bash
    84  kubectl autoscale deployment helloworld-v1 --cpu-percent=50 --min=1 --max=10
    85  kubectl autoscale deployment helloworld-v2 --cpu-percent=50 --min=1 --max=10
    86  kubectl get hpa
    87  ```
    88  
    89  ## Generate load
    90  
    91  ```bash
    92  ./loadgen.sh &
    93  ./loadgen.sh & # run it twice to generate lots of load
    94  ```
    95  
    96  Wait for about 2 minutes and then check the number of replicas:
    97  
    98  ```bash
    99  kubectl get hpa
   100  ```
   101  
   102  If the autoscaler is functioning correctly, the `REPLICAS` column should have a value > 1.
   103  
   104  ## Cleanup
   105  
   106  ```bash
   107  kubectl delete -f helloworld.yaml
   108  kubectl delete -f helloworld-gateway.yaml
   109  kubectl delete hpa helloworld-v1 helloworld-v2
   110  ```