Spring/spring-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rationalize reference documentation anchors

Browse Source 
Closes gh-26296
This commit is contained in:
Phillip Webb
2021-04-28 21:51:19 -07:00
parent 3d9eb9e413
commit bd3f4d74be
17 changed files with 4147 additions and 1040 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment.adoc
View File

@@ -9,7 +9,7 @@ This section covers some of the more common deployment scenarios.
[[containers-deployment]]
[[deployment.containers]]
== Deploying to Containers
If you are running your application from a container, you can use an executable jar, but it is also often an advantage to explode it and run it in a different way.
Certain PaaS implementations may also choose to unpack archives before they run.
@@ -36,11 +36,11 @@ Once you have unpacked the jar file, you can also get an extra boost to startup
NOTE: Using the `JarLauncher` over the application's main method has the added benefit of a predictable classpath order.
The jar contains a `classpath.idx` file which is used by the `JarLauncher` when constructing the classpath.
More efficient container images can also be created by <<spring-boot-features.adoc#boot-features-container-images-docker,creating separate layers>> for your dependencies and application classes and resources (which normally change more frequently).
More efficient container images can also be created by <<spring-boot-features.adoc#features.container-images.building.dockerfiles,creating separate layers>> for your dependencies and application classes and resources (which normally change more frequently).
[[cloud-deployment]]
[[deployment.cloud]]
== Deploying to the Cloud
Spring Boot's executable jars are ready-made for most popular cloud PaaS (Platform-as-a-Service) providers.
These providers tend to require that you "`bring your own container`".
@@ -55,11 +55,11 @@ It minimizes divergence between development and production environments.
Ideally, your application, like a Spring Boot executable jar, has everything that it needs to run packaged within it.
In this section, we look at what it takes to get the <<getting-started.adoc#getting-started-first-application, application that we developed>> in the "`Getting Started`" section up and running in the Cloud.
In this section, we look at what it takes to get the <<getting-started.adoc#getting-started.first-application, application that we developed>> in the "`Getting Started`" section up and running in the Cloud.
[[cloud-deployment-cloud-foundry]]
[[deployment.cloud.cloud-foundry]]
=== Cloud Foundry
Cloud Foundry provides default buildpacks that come into play if no other buildpack is specified.
The Cloud Foundry https://github.com/cloudfoundry/java-buildpack[Java buildpack] has excellent support for Spring applications, including Spring Boot.
@@ -127,7 +127,7 @@ In the preceding example, you could find it at `\https://acloudyspringtime.cfapp
[[cloud-deployment-cloud-foundry-services]]
[[deployment.cloud.cloud-foundry.binding-to-services]]
==== Binding to Services
By default, metadata about the running application as well as service connection information is exposed to the application as environment variables (for example: `$VCAP_SERVICES`).
This architecture decision is due to Cloud Foundry's polyglot (any language and platform can be supported as a buildpack) nature.
@@ -160,16 +160,16 @@ TIP: The https://github.com/pivotal-cf/java-cfenv/[Java CFEnv] project is a bett
[[cloud-deployment-kubernetes]]
[[deployment.cloud.kubernetes]]
=== Kubernetes
Spring Boot auto-detects Kubernetes deployment environments by checking the environment for `"*_SERVICE_HOST"` and `"*_SERVICE_PORT"` variables.
You can override this detection with the configprop:spring.main.cloud-platform[] configuration property.
Spring Boot helps you to <<spring-boot-features.adoc#boot-features-application-availability,manage the state of your application>> and export it with <<production-ready-features.adoc#production-ready-kubernetes-probes, HTTP Kubernetes Probes using Actuator>>.
Spring Boot helps you to <<spring-boot-features.adoc#features.spring-application.application-availability,manage the state of your application>> and export it with <<production-ready-features.adoc#actuator.endpoints.kubernetes-probes, HTTP Kubernetes Probes using Actuator>>.
[[cloud-deployment-kubernetes-container-lifecycle]]
[[deployment.cloud.kubernetes.container-lifecycle]]
==== Kubernetes Container Lifecycle
When Kubernetes deletes an application instance, the shutdown process involves several subsystems concurrently: shutdown hooks, unregistering the service, removing the instance from the load-balancer...
Because this shutdown processing happens in parallel (and due to the nature of distributed systems), there is a window during which traffic can be routed to a pod that has also begun its shutdown processing.
@@ -190,11 +190,11 @@ spec:
command: ["sh", "-c", "sleep 10"]
----
Once the pre-stop hook has completed, SIGTERM will be sent to the container and <<spring-boot-features#boot-features-graceful-shutdown,graceful shutdown>> will begin, allowing any remaining in-flight requests to complete.
Once the pre-stop hook has completed, SIGTERM will be sent to the container and <<spring-boot-features#features.graceful-shutdown,graceful shutdown>> will begin, allowing any remaining in-flight requests to complete.
[[cloud-deployment-heroku]]
[[deployment.cloud.heroku]]
=== Heroku
Heroku is another popular PaaS platform.
To customize Heroku builds, you provide a `Procfile`, which provides the incantation required to deploy an application.
@@ -263,7 +263,7 @@ For more details, refer to https://devcenter.heroku.com/articles/deploying-sprin
[[cloud-deployment-openshift]]
[[deployment.cloud.openshift]]
=== OpenShift
https://www.openshift.com/[OpenShift] has many resources describing how to deploy Spring Boot applications, including:
@@ -274,7 +274,7 @@ https://www.openshift.com/[OpenShift] has many resources describing how to deplo
[[cloud-deployment-aws]]
[[deployment.cloud.aws]]
=== Amazon Web Services (AWS)
Amazon Web Services offers multiple ways to install Spring Boot-based applications, either as traditional web applications (war) or as executable jar files with an embedded web server.
The options include:
@@ -290,14 +290,14 @@ In this document, we describe to approach using AWS Elastic Beanstalk.
[[cloud-deployment-aws-beanstalk]]
[[deployment.cloud.aws.beanstalk]]
==== AWS Elastic Beanstalk
As described in the official https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_Java.html[Elastic Beanstalk Java guide], there are two main options to deploy a Java application.
You can either use the "`Tomcat Platform`" or the "`Java SE platform`".
[[cloud-deployment-aws-tomcat-platform]]
[[deployment.cloud.aws.beanstalk.tomcat-platform]]
===== Using the Tomcat Platform
This option applies to Spring Boot projects that produce a war file.
No special configuration is required.
@@ -305,7 +305,7 @@ You need only follow the official guide.
[[cloud-deployment-aws-java-se-platform]]
[[deployment.cloud.aws.beanstalk.java-se-platform]]
===== Using the Java SE Platform
This option applies to Spring Boot projects that produce a jar file and run an embedded web container.
Elastic Beanstalk environments run an nginx instance on port 80 to proxy the actual application, running on port 5000.
@@ -347,14 +347,14 @@ You can also create single instance environments by using the CLI and the follow
[[cloud-deployment-aws-summary]]
[[deployment.cloud.aws.summary]]
==== Summary
This is one of the easiest ways to get to AWS, but there are more things to cover, such as how to integrate Elastic Beanstalk into any CI / CD tool, use the Elastic Beanstalk Maven plugin instead of the CLI, and others.
There is a https://exampledriven.wordpress.com/2017/01/09/spring-boot-aws-elastic-beanstalk-example/[blog post] covering these topics more in detail.
[[cloud-deployment-boxfuse]]
[[deployment.cloud.boxfuse]]
=== Boxfuse and Amazon Web Services
https://boxfuse.com/[Boxfuse] works by turning your Spring Boot executable jar or war into a minimal VM image that can be deployed unchanged either on VirtualBox or on AWS.
Boxfuse comes with deep integration for Spring Boot and uses the information from your Spring Boot configuration file to automatically configure ports and health check URLs.
@@ -402,7 +402,7 @@ See the blog post on https://boxfuse.com/blog/spring-boot-ec2.html[deploying Spr
[[cloud-deployment-gae]]
[[deployment.cloud.google]]
=== Google Cloud
Google Cloud has several options that can be used to launch Spring Boot applications.
The easiest to get started with is probably App Engine, but you could also find ways to run Spring Boot in a container with Container Engine or on a virtual machine with Compute Engine.
@@ -458,10 +458,10 @@ Then deploy with `mvn appengine:deploy` (if you need to authenticate first, the
[[deployment-install]]
[[deployment.installing]]
== Installing Spring Boot Applications
In addition to running Spring Boot applications by using `java -jar`, it is also possible to make fully executable applications for Unix systems.
A fully executable jar can be executed like any other executable binary or it can be <<deployment-service,registered with `init.d` or `systemd`>>.
A fully executable jar can be executed like any other executable binary or it can be <<deployment.installing.nix-services,registered with `init.d` or `systemd`>>.
This helps when installing and managing Spring Boot applications in common production environments.
CAUTION: Fully executable jars work by embedding an extra script at the front of the file.
@@ -500,22 +500,22 @@ The directory containing the jar is used as your application's working directory
[[deployment-install-supported-operating-systems]]
[[deployment.installing.supported-operating-systems]]
=== Supported Operating Systems
The default script supports most Linux distributions and is tested on CentOS and Ubuntu.
Other platforms, such as OS X and FreeBSD, require the use of a custom `embeddedLaunchScript`.
[[deployment-service]]
[[deployment.installing.nix-services]]
=== Unix/Linux Services
Spring Boot application can be easily started as Unix/Linux services by using either `init.d` or `systemd`.
[[deployment-initd-service]]
[[deployment.installing.nix-services.init-d]]
==== Installation as an init.d Service (System V)
If you configured Spring Boot's Maven or Gradle plugin to generate a <<deployment-install, fully executable jar>>, and you do not use a custom `embeddedLaunchScript`, your application can be used as an `init.d` service.
If you configured Spring Boot's Maven or Gradle plugin to generate a <<deployment.installing, fully executable jar>>, and you do not use a custom `embeddedLaunchScript`, your application can be used as an `init.d` service.
To do so, symlink the jar to `init.d` to support the standard `start`, `stop`, `restart`, and `status` commands.
The script supports the following features:
@@ -551,7 +551,7 @@ For example, on Debian, you could use the following command:
[[deployment-initd-service-securing]]
[[deployment.installing.nix-services.init-d.securing]]
===== Securing an init.d Service
NOTE: The following is a set of guidelines on how to secure a Spring Boot application that runs as an init.d service.
It is not intended to be an exhaustive list of everything that should be done to harden an application and the environment in which it runs.
@@ -602,7 +602,7 @@ Use `chmod` so that the file can only be read by the owner and use `chown` to ma
[[deployment-systemd-service]]
[[deployment.installing.nix-services.system-d]]
==== Installation as a systemd Service
`systemd` is the successor of the System V init system and is now being used by many modern Linux distributions.
Although you can continue to use `init.d` scripts with `systemd`, it is also possible to launch Spring Boot applications by using `systemd` '`service`' scripts.
@@ -643,7 +643,7 @@ Refer to `man systemctl` for more details.
[[deployment-script-customization]]
[[deployment.installing.nix-services.script-customization]]
==== Customizing the Startup Script
The default embedded startup script written by the Maven or Gradle plugin can be customized in a number of ways.
For most people, using the default script along with a few customizations is usually enough.
@@ -651,7 +651,7 @@ If you find you cannot customize something that you need to, use the `embeddedLa
[[deployment-script-customization-when-it-written]]
[[deployment.installing.nix-services.script-customization.when-written]]
===== Customizing the Start Script When It Is Written
It often makes sense to customize elements of the start script as it is written into the jar file.
For example, init.d scripts can provide a "`description`".
@@ -759,7 +759,7 @@ The following property substitutions are supported with the default script:
[[deployment-script-customization-when-it-runs]]
[[deployment.installing.nix-services.script-customization.when-running]]
===== Customizing a Script When It Runs
For items of the script that need to be customized _after_ the jar has been written, you can use environment variables or a <<deployment-script-customization-conf-file, config file>>.
@@ -838,11 +838,11 @@ For example, a jar named `/var/myapp/myapp.jar` uses the configuration file name
TIP: If you do not like having the config file next to the jar file, you can set a `CONF_FOLDER` environment variable to customize the location of the config file.
To learn about securing this file appropriately, see <<deployment-initd-service-securing,the guidelines for securing an init.d service>>.
To learn about securing this file appropriately, see <<deployment.installing.nix-services.init-d.securing,the guidelines for securing an init.d service>>.
[[deployment-windows]]
[[deployment.installing.windows-services]]
=== Microsoft Windows Services
A Spring Boot application can be started as a Windows service by using https://github.com/kohsuke/winsw[`winsw`].
@@ -850,7 +850,7 @@ A (https://github.com/snicoll/spring-boot-daemon[separately maintained sample])
[[deployment-whats-next]]
[[deployment.whats-next]]
== What to Read Next
Check out the https://www.cloudfoundry.org/[Cloud Foundry], https://www.heroku.com/[Heroku], https://www.openshift.com[OpenShift], and https://boxfuse.com[Boxfuse] web sites for more information about the kinds of features that a PaaS can offer.
These are just four of the most popular Java PaaS providers.