Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 1945:88477c5d2751

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moved "health_check" and "match" to ngx_http_upstream_hc_module.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 30 Mar 2017 21:26:44 +0300
parents a58b35cc0823
children 5c55b7054b58
comparison
equal deleted inserted replaced
1944:dbf6f05f0808 1945:88477c5d2751
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9 9
10 <module name="Module ngx_http_upstream_module" 10 <module name="Module ngx_http_upstream_module"
11 link="/en/docs/http/ngx_http_upstream_module.html" 11 link="/en/docs/http/ngx_http_upstream_module.html"
12 lang="en" 12 lang="en"
13 rev="59"> 13 rev="60">
14 14
15 <section id="summary"> 15 <section id="summary">
16 16
17 <para> 17 <para>
18 The <literal>ngx_http_upstream_module</literal> module 18 The <literal>ngx_http_upstream_module</literal> module
47 } 47 }
48 </example> 48 </example>
49 </para> 49 </para>
50 50
51 <para> 51 <para>
52 Dynamically configurable group, 52 Dynamically configurable group with
53 periodic <link doc="ngx_http_upstream_hc_module.xml">health checks</link> is
53 available as part of our 54 available as part of our
54 <commercial_version>commercial subscription</commercial_version>: 55 <commercial_version>commercial subscription</commercial_version>:
55 <example> 56 <example>
56 resolver 10.0.0.1; 57 resolver 10.0.0.1;
57 58
319 <literal>slow_start</literal>=<value>time</value> 320 <literal>slow_start</literal>=<value>time</value>
320 </tag-name> 321 </tag-name>
321 <tag-desc> 322 <tag-desc>
322 sets the <value>time</value> during which the server will recover its weight 323 sets the <value>time</value> during which the server will recover its weight
323 from zero to a nominal value, when unhealthy server becomes 324 from zero to a nominal value, when unhealthy server becomes
324 <link id="health_check">healthy</link>, 325 <link doc="ngx_http_upstream_hc_module.xml" id="health_check">healthy</link>,
325 or when the server becomes available after a period of time 326 or when the server becomes available after a period of time
326 it was considered <link id="fail_timeout">unavailable</link>. 327 it was considered <link id="fail_timeout">unavailable</link>.
327 Default value is zero, i.e. slow start is disabled. 328 Default value is zero, i.e. slow start is disabled.
328 <note> 329 <note>
329 The parameter cannot be used along with the 330 The parameter cannot be used along with the
727 If the <literal>inflight</literal> parameter is specified (1.11.6), 728 If the <literal>inflight</literal> parameter is specified (1.11.6),
728 incomplete requests are also taken into account. 729 incomplete requests are also taken into account.
729 <note> 730 <note>
730 Prior to version 1.11.6, incomplete requests were taken into account by default. 731 Prior to version 1.11.6, incomplete requests were taken into account by default.
731 </note> 732 </note>
732 </para>
733
734 <para>
735 <note>
736 This directive is available as part of our
737 <commercial_version>commercial subscription</commercial_version>.
738 </note>
739 </para>
740
741 </directive>
742
743
744 <directive name="health_check">
745 <syntax>[<value>parameters</value>]</syntax>
746 <default/>
747 <context>location</context>
748
749 <para>
750 Enables periodic health checks of the servers in a
751 <link id="upstream">group</link> referenced in the surrounding location.
752 </para>
753
754 <para>
755 The following optional parameters are supported:
756 <list type="tag">
757
758 <tag-name id="interval">
759 <literal>interval</literal>=<value>time</value>
760 </tag-name>
761 <tag-desc>
762 sets the interval between two consecutive health checks,
763 by default, 5 seconds.
764 </tag-desc>
765
766 <tag-name id="health_check_jitter">
767 <literal>jitter</literal>=<value>time</value>
768 </tag-name>
769 <tag-desc>
770 sets the time within which
771 each health check will be randomly delayed,
772 by default, there is no delay.
773 </tag-desc>
774
775 <tag-name id="fails">
776 <literal>fails</literal>=<value>number</value>
777 </tag-name>
778 <tag-desc>
779 sets the number of consecutive failed health checks of a particular server
780 after which this server will be considered unhealthy,
781 by default, 1.
782 </tag-desc>
783
784 <tag-name id="passes">
785 <literal>passes</literal>=<value>number</value>
786 </tag-name>
787 <tag-desc>
788 sets the number of consecutive passed health checks of a particular server
789 after which the server will be considered healthy,
790 by default, 1.
791 </tag-desc>
792
793 <tag-name id="uri">
794 <literal>uri</literal>=<value>uri</value>
795 </tag-name>
796 <tag-desc>
797 defines the URI used in health check requests,
798 by default, “<literal>/</literal>”.
799 </tag-desc>
800
801 <tag-name id="health_check_mandatory">
802 <literal>mandatory</literal>
803 </tag-name>
804 <tag-desc>
805 sets the initial “checking” state for a server
806 until the first health check is completed (1.11.7).
807 If the parameter is not specified,
808 the server will be initially considered healthy.
809 </tag-desc>
810
811 <tag-name id="hc_match">
812 <literal>match</literal>=<value>name</value>
813 </tag-name>
814 <tag-desc>
815 specifies the <literal>match</literal> block configuring the tests that a
816 response should pass in order for a health check to pass.
817 By default, the response should have status code 2xx or 3xx.
818 </tag-desc>
819
820 <tag-name id="health_check_port">
821 <literal>port</literal>=<value>number</value>
822 </tag-name>
823 <tag-desc>
824 defines the port used when connecting to a server
825 to perform a health check (1.9.7).
826 By default, equals the <link id="server"/> port.
827 </tag-desc>
828
829 </list>
830 </para>
831
832 <para>
833 For example,
834 <example>
835 location / {
836 proxy_pass http://backend;
837 health_check;
838 }
839 </example>
840 will send “<literal>/</literal>” requests to each
841 server in the <literal>backend</literal> group every five seconds.
842 If any communication error or timeout occurs, or a
843 proxied server responds with the status code other than
844 2xx or 3xx, the health check will fail, and the server will
845 be considered unhealthy.
846 Client requests are not passed to unhealthy servers
847 and servers in the “checking” state.
848 </para>
849
850 <para>
851 Health checks can be configured to test the status code of a response,
852 presence of certain header fields and their values,
853 and the body contents.
854 Tests are configured separately using the <link id="match"/> directive
855 and referenced in the <literal>match</literal> parameter.
856 For example:
857 <example>
858 http {
859 server {
860 ...
861 location / {
862 proxy_pass http://backend;
863 health_check match=welcome;
864 }
865 }
866
867 match welcome {
868 status 200;
869 header Content-Type = text/html;
870 body ~ "Welcome to nginx!";
871 }
872 }
873 </example>
874 This configuration shows that in order for a health check to pass, the response
875 to a health check request should succeed,
876 have status 200, content type “<literal>text/html</literal>”,
877 and contain “<literal>Welcome to nginx!</literal>” in the body.
878 </para>
879
880 <para>
881 The server group must reside in the <link id="zone">shared memory</link>.
882 </para>
883
884 <para>
885 If several health checks are defined for the same group of servers,
886 a single failure of any check will make the corresponding server be
887 considered unhealthy.
888 </para>
889
890 <para>
891 <note>
892 Please note that most of the variables will have empty values
893 when used with health checks.
894 </note>
895 </para>
896
897 <para>
898 <note>
899 This directive is available as part of our
900 <commercial_version>commercial subscription</commercial_version>.
901 </note>
902 </para>
903
904 </directive>
905
906
907 <directive name="match">
908 <syntax block="yes"><value>name</value></syntax>
909 <default/>
910 <context>http</context>
911
912 <para>
913 Defines the named test set used to verify responses to health check requests.
914 </para>
915
916 <para>
917 The following items can be tested in a response:
918 <list type="tag">
919
920 <tag-name><literal>status 200;</literal></tag-name>
921 <tag-desc>status is 200</tag-desc>
922
923 <tag-name><literal>status ! 500;</literal></tag-name>
924 <tag-desc>status is not 500</tag-desc>
925
926 <tag-name><literal>status 200 204;</literal></tag-name>
927 <tag-desc>status is 200 or 204</tag-desc>
928
929 <tag-name><literal>status ! 301 302;</literal></tag-name>
930 <tag-desc>status is neither 301 nor 302</tag-desc>
931
932 <tag-name><literal>status 200-399;</literal></tag-name>
933 <tag-desc>status is in the range from 200 to 399</tag-desc>
934
935 <tag-name><literal>status ! 400-599;</literal></tag-name>
936 <tag-desc>status is not in the range from 400 to 599</tag-desc>
937
938 <tag-name><literal>status 301-303 307;</literal></tag-name>
939 <tag-desc>status is either 301, 302, 303, or 307</tag-desc>
940
941 </list>
942
943 <list type="tag">
944
945 <tag-name><literal>header Content-Type = text/html;</literal></tag-name>
946 <tag-desc>
947 header contains <header>Content-Type</header>
948 with value <literal>text/html</literal>
949 </tag-desc>
950
951 <tag-name><literal>header Content-Type != text/html;</literal></tag-name>
952 <tag-desc>
953 header contains <header>Content-Type</header>
954 with value other than <literal>text/html</literal>
955 </tag-desc>
956
957 <tag-name><literal>header Connection ~ close;</literal></tag-name>
958 <tag-desc>
959 header contains <header>Connection</header>
960 with value matching regular expression <literal>close</literal>
961 </tag-desc>
962
963 <tag-name><literal>header Connection !~ close;</literal></tag-name>
964 <tag-desc>
965 header contains <header>Connection</header>
966 with value not matching regular expression <literal>close</literal>
967 </tag-desc>
968
969 <tag-name><literal>header Host;</literal></tag-name>
970 <tag-desc>header contains <header>Host</header></tag-desc>
971
972 <tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name>
973 <tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc>
974
975 </list>
976
977 <list type="tag">
978
979 <tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name>
980 <tag-desc>
981 body matches regular expression “<literal>Welcome to nginx!</literal>”
982 </tag-desc>
983
984 <tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name>
985 <tag-desc>
986 body does not match regular expression “<literal>Welcome to nginx!</literal>”
987 </tag-desc>
988
989 </list>
990 </para>
991
992 <para>
993 If several tests are specified,
994 the response matches only if it matches all tests.
995 <note>
996 Only the first 256k of the response body are examined.
997 </note>
998 </para>
999
1000 <para>
1001 Examples:
1002 <example>
1003 # status is 200, content type is "text/html",
1004 # and body contains "Welcome to nginx!"
1005 match welcome {
1006 status 200;
1007 header Content-Type = text/html;
1008 body ~ "Welcome to nginx!";
1009 }
1010 </example>
1011
1012 <example>
1013 # status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
1014 match not_redirect {
1015 status ! 301-303 307;
1016 header ! Refresh;
1017 }
1018 </example>
1019
1020 <example>
1021 # status ok and not in maintenance mode
1022 match server_ok {
1023 status 200-399;
1024 body !~ "maintenance mode";
1025 }
1026 </example>
1027
1028 </para> 733 </para>
1029 734
1030 <para> 735 <para>
1031 <note> 736 <note>
1032 This directive is available as part of our 737 This directive is available as part of our