You configure your App Engine app's settings in the app.yaml
file.
This file specifies how URL paths correspond to request handlers and
static files.
The app.yaml file also contains information about your
app's code, such as the runtime and the latest version
identifier.
Each service
in your app has its own app.yaml file, which acts as a descriptor for its
deployment. You must first create the app.yaml file for the default service
before you can create and deploy app.yaml files for additional services within
your app.
Directory structure
Each service must have an app.yaml file in its root directory.
To learn more about structuring multiple services in your app, see
Structuring Web Services in App Engine.
Example
The following is an example of an app.yaml file for a Go
application:
The YAML format supports comments. A line that begins with a pound (#)
character is ignored:
# This is a comment.
URL and file path patterns use POSIX extended regular expression
syntax, excluding collating
elements and collation classes. Back-references to grouped matches (e.g. \1)
are supported, as are these Perl extensions: \w \W \s \S \d \D.
Runtime and app elements
Element
Description
application
The recommended approach is to remove the application
element from your app.yaml file and instead, use a
command-line flag to specify your application ID:
To use the goapp deploy command, you specify the
-application flag:
The application ID is the GCP Console project ID
that you specified when you created the application in the
Google Cloud Platform Console.
api_version
Required.
The version of the API in the given runtime environment that is used
by your app.
When Google announces support for a new version of a
runtime environment's API, your deployed app will continue to use the
one for which it was written. To upgrade your app to a new version of
the API, you change this value and then redeploy your app to App
Engine. When you specify the go1
value, the latest supported runtime environment is used each time you
deploy that app (currently go1.9).
You can specify the following versions of the Go runtime
environment: go1 and go1.9
Default. Uses scattered auto IDs that are large well-distributed
integers that are small enough to be represented by 64-bit floats.
legacy
The legacy option will be deprecated in a future release and will
eventually be removed. For more information, see the blog post announcing this
change.
default_expiration
Optional. Sets a global default cache period for all static
file handlers for an application. You can also configure a cache duration for specific static file
handlers. The value is a string of numbers and units, separated by
spaces, where units can be d for days, h for hours, m for minutes, and
s for seconds. For example, "4d 5h" sets cache expiration
to 4 days and 5 hours after the file is first requested. If omitted,
the production server sets the expiration to 10 minutes.
Example:
runtime: go
api_version: go1
default_expiration: "4d 5h"
handlers:
# ...
Optional.
You can define environment variables in your app.yaml
file to make them available to your app.
Environment variables that are prefixed with
GAE are reserved for system use and not allowed in the
app.yaml file.
Example:
env_variables:
MY_VAR: 'my value'
where MY_VAR and my value are the name and
value of the environment variable that you want to define and each
environment variable entry is indented two spaces under the
env_variables element.
You can then get these values using os.Getenv:
import "os"
//...
if v := os.Getenv("MY_VAR"); v != "" {
//...
}
error_handlers
Optional.
Used to configure custom error pages that are returned for different
error types.
This element can contain the following elements:
error_code
Optional. The error_code can be one of the following:
Served if a deadline is reached before there is a response from
your app.
The error_code is optional; if it's not specified, the given file
is the default error response for your app.
file
Each file entry indicates a static file that should be served in
place of the generic error response. If you specify a
file element without a corresponding
error_code element, the static file will be the default
error page for your app.
The custom error data must be less than 10 kilobytes.
Required.
A list of URL patterns and descriptions of how they should be handled.
App Engine can handle URLs by executing application code, or
by serving static files uploaded with the code, such as images, CSS,
or JavaScript.
Optional.
The includes directive allows you to include the
configuration file for any library or service throughout your
application. For example, you might include a user administration
library as follows:
includes:
- lib/user_admin.yaml
App Engine resolves the included path in the following order:
Absolute or relative path to the working directory. The specified
path resolves to a file.
Relative to the application's directory, which is also known as the
basepath. The basepath and path resolve to a file.
Relative to the file that included the current file. The location of
the referring file and the include path resolve to the included
file.
If the include directive specifies a directory, then App
Engine looks in that directory for a file called
include.yaml. If the include directive is a file, then
that specific file is included. Using includes retrieves
only the following types of directives from the destination file (if
present):
Included skip_files patterns are added to those in the
including app.yaml, or to the default list if there is no
explicit list in app.yaml. Note that
skip_files compares absolute paths.
inbound_services
Optional.
Applications must enable those services before it can receive inbound
requests. You can enable the service for a Go app
by including an inbound_services section in the
app.yaml file.
The following values are available depending on your
service's
scaling:
Automatic scaling
F1, F2, F4, F4_1G
Default:F1 is assigned if you do not specify an
instance class along with the automatic_scaling element.
Basic and manual scaling
B1, B2, B4, B4_1G, B8
Default:B2 is assigned if you do not specify an
instance class along with the basic_scaling element or the manual_scaling element.
Note: If instance_class
is set to F2 or higher, you can optimize your instances by setting
max_concurrent_requests to a value higher than 10, which is the default.
To find the optimal value, gradually increase it and monitor the performance of your
application.
module
Note: Modules are now named Services.
To manage your app with the gcloud tool, use the
service element instead.
To use the appcfg tool, services must be declared in
app.yaml files as modules, for example:
module: service-name
Required if creating a
service.
Optional for the default
service. Each service and each version must have a name. A name can
contain numbers, letters, and hyphens. Combined length of service and version cannot be longer than 63
characters and cannot start or end with a hyphen. Choose a unique name
for each service and each version. Don't reuse names between services
and versions.
runtime
Required. The name of the runtime environment that is used by your
app. To specify Go, use:
runtime: go
service
Services were formerly known as Modules.
Supported only by the gcloud tool or Cloud SDK-based
plugins, for example: gcloud app deploy.
Required if creating a
service.
Optional for the default
service. Each service and each version must have a name. A name can
contain numbers, letters, and hyphens. Combined length of service and version cannot be longer than 63
characters and cannot start or end with a hyphen. Choose a unique name
for each service and each version. Don't reuse names between services
and versions.
Example:
service: service-name
Note: The
gcloud app
deploy command is backwards
compatible and supports existing app.yaml files that
include services declared as modules, for example:
module: service-name
skip_files
Optional.
The skip_files element specifies which files in the
application directory are not to be uploaded to App Engine.
The value is either a regular expression, or a list of regular
expressions. Any filename that matches any of the regular expressions
is omitted from the list of files to upload when the application is
uploaded. Filenames are relative to the project directory.
The default pattern excludes Emacs backup files with names of the form
#...# and ...~, .pyc and
.pyo files, files in an RCS revision control
directory, and Unix hidden files with names beginning with a dot
(.).
To extend the above regular expression list, copy and paste the above
list into your app.yaml and add your own regular
expressions. For example, to skip files whose names end in
.bak in addition to the default patterns, add an entry
like this for skip_files:
To skip a full directory, add the directory name to
the list. For example, to skip a directory named logs,
add the following line to the previously described ones:
skip_files:
- logs/
version
The recommended approach is to remove the version
element from your app.yaml file and instead, use a
command-line flag to specify your version ID:
To use the goapp deploy command, you specify the
-version flag:
An identifier for the version of your application code that you deploy
to App Engine.
The version ID can contain lowercase letters, digits, and hyphens. It
cannot begin with the prefix ah- and the names
default and latest are reserved and cannot
be used.
Note: Version names should begin with a letter, to distinguish them
from numeric instances which are always specified by a number. This
avoids the ambiguity with URLs like
123.my-service.appspot.com, which can be interpreted two
ways: If version “123” exists, the target will be version “123” of the
given service. If that version does not exist, the target will be
instance number 123 of the default version of the service.
Each version of an application retains its own copy of
app.yaml. When an application is uploaded, the version
mentioned in the app.yaml file being uploaded is the
version that gets created or replaced by the upload. An administrator
can change which version of the application is serving traffic by
using the Google Cloud Platform Console, and can also
test
other versions before configuring them to receive traffic.
Handlers element
The handlers element is a required element in the
app.yaml configuration file. The element provides a list of URL
patterns and descriptions of how they should be handled. App Engine can
handle URLs by executing application code, or by serving static files uploaded
with the code, such as images, CSS, or JavaScript.
Patterns are evaluated in the order they appear in the app.yaml file, from
top to bottom. The first mapping whose pattern matches the URL is the one used
to handle the request.
The following table lists the subelements of the handlers element that control
the behavior for scripts, static files,
static directories, and other settings.
Element
Description
application_readable
Optional. Boolean. By default, files declared in static file handlers
are uploaded as static data and are only served to end users. They
cannot be read by an application. If this field is set to true, the
files are also uploaded as code data so your application can read them.
Both uploads are charged against your code and static data storage resource quotas.
auth_fail_action
Optional.
Describes the action taken when the login element is
specified for a handler and the user is not logged in. Has two
possible values:
redirect
Default. The user is redirected to the Google sign-in page, or
/_ah/login_required if OpenID authentication is used.
The user is redirected back to the application URL after signing in
or creating an account.
unauthorized
The request is rejected with an HTTP 401 status code
and an error message.
If an application needs different behavior, the application itself can
implement the handling of user logins. See the Users
API for more information.
The following example requires a login for the /profile/
directory and an administrator login for the /admin/
directory:
You can configure a handler to refuse access to protected URLs when
the user is not signed in, instead of redirecting the user to the
sign-in page, by adding auth_fail_action: unauthorized to
the handler's configuration:
Optional.
The length of time a static file served by this handler should be
cached by web proxies and browsers. The value is a string of
numbers and units, separated by spaces, where units can be
d for days, h for hours, m for
minutes, and s for seconds. For example,
"4d 5h" sets cache expiration to 4 days and 5 hours after
the file is first requested. If omitted, the application's
default_expiration is used. See Static cache expiration for more
details.
http_headers
Optional. You can set HTTP
headers for responses of your static file or directory
handlers. If you need to set HTTP headers
in your script handlers, you should instead do that in your app's
code.
Example
handlers:
- url: /images
static_dir: static/images
http_headers:
X-Foo-Header: foo
X-Bar-Header: bar value
# ...
CORS Support
One important use of this feature is to support cross-origin resource
sharing (CORS), such as accessing files hosted by another
App Engine app.
For example, you could have a game app mygame.appspot.com
that accesses assets hosted by myassets.appspot.com.
However, if mygame attempts to make a JavaScript
XMLHttpRequest to myassets, it will not
succeed unless the handler for myassets returns an
Access-Control-Allow-Origin: response header containing
the value http://mygame.appspot.com.
Here is how you would make your static file handler return that
required response header value:
Note: if you wanted to allow everyone to access your assets, you could
use the wildcard '*', instead of
http://mygame.appspot.com.
login
Optional.
Determines whether the URL handler requires that the user is signed
in. This element has three possible values:
optional
Default. Does not require that the user is signed in.
required
If the user has signed in, the handler proceeds normally. Otherwise,
the action given in auth_fail_action
is taken.
admin
As with required, performs auth_fail_action
if the user is not signed in. In addition, if the user is not an
administrator for the application, they are given an error message
regardless of the auth_fail_action
setting. If the user is an administrator, the handler proceeds.
When a URL handler with a login setting other than
optional matches a URL, the handler first checks whether
the user has signed in to the application using its
authentication option. If not, by default, the user is redirected
to the sign-in page. You can also use auth_fail_action to
configure the app to simply reject requests for a handler from users
who are not properly authenticated, instead of redirecting the user to
the sign-in page.
Note: the admin login restriction is also satisfied for
internal requests for which App Engine sets appropriate
X-Appengine special headers. For example,
cron scheduled tasks satisfy the admin
restriction, because App Engine sets an HTTP header
X-AppEngine-Cron: true on the respective requests.
However, the requests would not satisfy the
required login restriction, because cron scheduled tasks
are not run as any user.
mime_type
Optional. If specified, all files served by this handler will be
served using the specified MIME type. If not specified, the MIME type
for a file will be derived from the file's filename extension.
If the same file is uploaded with multiple extensions, the resulting
extension can depend on the order in which the uploads occurred.
Optional. redirect_http_response_code is used with the
secure setting to set the HTTP response code returned
when performing a redirect required by how the secure
setting is configured.
redirect_http_response_code element has the following
possible values:
When a user's request is redirected, the HTTP status code will be set
to the value of the redirect_http_response_code
parameter. If the parameter is not present, 302 will be returned.
script
Optional.
Specifies the path to the script from the application root
directory:
For Go apps, script should always have a value of
_go_app.
handlers:
# The root URL (/) is handled by the Go application.
# No other URLs match this pattern.
- url: /
script: _go_app
# The URL /index.html is also handled by the Go application.
- url: /index\.html
script: _go_app
# A regular expression indicating that it should be handled
# by the Go application.
- url: /browse/(books|videos|tools)
script: _go_app
# All other URLs are handled by the Go application.
- url: /.*
script: _go_app
secure
Optional. Any URL handler can use the secure setting,
including script handlers and
static file handlers. The secure element has the following
possible values:
optional
Both HTTP and HTTPS requests with URLs that match the handler
succeed without redirects. The application can examine the request
to determine which protocol was used, and respond accordingly. This
is the default when secure is not provided for a
handler.
never
Requests for a URL that match this handler that use HTTPS are
automatically redirected to the HTTP equivalent URL. When a user's
HTTPS request is redirected to be an HTTP request,
the query parameters are removed from the request. This prevents a
user from accidentally submitting query data over a non-secure
connection that was intended for a secure connection.
always
Requests for a URL that match this handler that do not use HTTPS are
automatically redirected to the HTTPS URL with the same path. Query
parameters are preserved for the redirect.
The development web server does not support HTTPS connections. It
ignores the secure parameter, so paths intended for use
with HTTPS can be tested using regular HTTP connections to the
development web server.
To
target a specific version of your app using the appspot.com
domain, you replace the periods that would usually separate the
subdomain components of the URL with the string "-dot-",
for example:
Google Accounts sign-in and sign-out are always performed using a
secure connection, unrelated to how the application's URLs are
configured.
static_dir
Optional. The path to the directory containing the static files, from
the application root directory. Everything after the end of the
matched url pattern is appended to
static_dir to form the full path to the requested file.
Each file in the static directory is served using the MIME type that
corresponds with its filename extension unless overridden by the
directory's mime_type setting. All of the files in the
given directory are uploaded as static files, and
none of them can be run as scripts.
All files in this directory are uploaded with your app as static
files. App Engine stores and serves static files separately
from your app's files. Static files are not available in the app's
file system by default. This can be changed by setting the application_readable option to true.
Example:
handlers:
# All URLs beginning with /stylesheets are treated as paths to
# static files in the stylesheets/ directory.
- url: /stylesheets
static_dir: stylesheets
# ...
static_files
Optional. A static file pattern handler associates a URL pattern with
paths to static files uploaded with the application. The URL pattern
regular expression can define regular expression groupings to be used
in the construction of the file path. You can use this instead of
static_dir to map to specific files in a directory
structure without mapping the entire directory.
Example:
handlers:
# All URLs ending in .gif .png or .jpg are treated as paths to
# static files in the static/ directory. The URL pattern is a
# regular expression, with a grouping that is inserted into the
# path to the file.
- url: /(.*\.(gif|png|jpg))$
static_files: static/\1
upload: static/.*\.(gif|png|jpg)$
# ...
App Engine stores and serves static files separately
from application files. Static files are not available in the
application's file system by default. This can be changed by setting
the application_readable option to true.
Static files cannot be the same as application code files.
If a static file path matches a path to a script used in a dynamic
handler, the script will not be available to the dynamic handler.
upload
Optional. A regular expression that matches the file paths for all
files that will be referenced by this handler. This is necessary
because the handler cannot determine which files in your application
directory correspond with the given url and
static_files patterns. Static files are uploaded and
handled separately from application files. The example
above might use the following upload pattern:
archives/(.*)/items/(.*)
url
Required element under handlers. The URL pattern, as a
regular expression. The expression can contain groupings that can be
referred to in the file path to the script with regular expression
back-references. For example,
/profile/(.*)/(.*) would match the URL
/profile/edit/manager and use
edit and manager as the first and second
groupings.
The URL pattern has some differences in behavior when used with the
following elements:
Uses a URL prefix. The regular express pattern should not contain
groupings when used with the static_dir element. All
URLs that begin with this prefix are handled by this handler, using
the portion of the URL after the prefix as part of the file path.
A static file pattern handler associates a URL pattern with paths to
static files uploaded with the application. The URL pattern regular
expression can define regular expression groupings to be used in the
construction of the file path. You can use this instead of
static_dir to map to specific files in a directory
structure without mapping the entire directory.
The following table lists the options for defining how you can specify that your
application should scale.
Element
Description
automatic_scaling
Optional. Automatic scaling is assumed by default with a default
instance class of F1 unless specified otherwise.
The automatic_scaling element sets minimum and maximum
levels for number of instances, latency, and concurrent connections
for a service.
This element can contain the following elements:
target_cpu_utilization
Optional. Specify a value between 0.5 and 0.95. The default is
0.6.
This parameter specifies
the CPU usage threshold at which new instances will be
started to handle traffic, enabling you to balance between
performance and cost, with lower values increasing performance and
increasing cost, and higher values decreasing performance but
also decreasing cost. For example, a value of 0.7 means that new
instances will be started after CPU usage reaches 70 percent.
Optional. Specify a value from 0.5 to 0.95. The default is
0.6.
Used with max_concurrent_requests to specify when
a new instance is started due to concurrent requests. When the
number of concurrent requests reaches a value equal to
max_concurrent_requests times
target_throughput_utilization, the scheduler starts
a new instance.
Optional. Specify a value between 0 and 2147483647, where zero
disables the setting.
This parameter specifies the maximum number of instances for App
Engine to create for this module version. This is useful to limit
the costs of a module.
Optional. The minimum number of instances for App Engine to
create for this module version. These instances serve traffic when
requests arrive, and continue to serve traffic even when
additional instances are started up as required to handle traffic.
Specify a value from 0 to 1000. You can set
the parameter to the value 0 to allow scaling to 0 instances to
lower costs when no requests are being served. Note that you are
charged for the number of instances specified whether they are
receiving traffic or not.
Optional. The number of concurrent requests an automatic scaling
instance can accept before the scheduler spawns a new instance
(Default: 10,
Maximum: 80).
Used with target_throughput_utilization to
specify when a new instance is started due to concurrent requests.
When the number of concurrent requests reaches a value equal to
max_concurrent_requests times
target_throughput_utilization, the scheduler starts
a new instance.
You might experience increased API latency if this setting is too
high. Note that the scheduler might spawn a new instance before
the actual maximum number of requests is reached.
Note: If instance_class
is set to F2 or higher, you can optimize your instances by setting
max_concurrent_requests to a value higher than 10, which is the default.
To find the optimal value, gradually increase it and monitor the performance of your
application.
max_idle_instances
Optional. The maximum number of idle instances that
App Engine should maintain for this version. Specify a
value from 1 to 1000, or automatic. The default
value is automatic.
Keep the following in mind:
A high maximum reduces the number of idle instances more
gradually when load levels return to normal after a spike. This
helps your application maintain steady performance through
fluctuations in request load, but also raises the number of idle
instances (and consequent running costs) during such periods of
heavy load.
A low maximum keeps running costs lower, but can degrade
performance in the face of volatile load levels.
Note: When settling back to normal levels after a
load spike, the number of idle instances can temporarily exceed
your specified maximum. However, you will not be charged for more
instances than the maximum number you've specified.
max_pending_latency
The maximum amount of time that App Engine should allow a request
to wait in the pending queue before starting additional instances
to handle requests so that pending latency is reduced. When this
threshold is reached, it is a signal to scale up, and results in
an increase in the number of instances. The default value is
30ms.
App Engine can create an instance at any time between the
time specified in min_pending_latency and
max_pending_latency. In other words, App Engine
will not create an instance to serve a pending request before the
time specified in min_pending_latency, but
App Engine will create an instance after
max_pending_latency is reached.
A low maximum means App Engine will start new instances
sooner for pending requests, improving performance but raising
running costs.
A high maximum means users might wait longer for their requests
to be served (if there are pending requests and no idle
instances to serve them), but your application will cost less to
run.
min_idle_instances
The number of instances to be kept running
and ready to serve traffic. Note that you are
charged for the number of instances specified whether they are
receiving traffic or not. This setting only applies to the version
that receives most of the traffic. Keep the following in mind:
A low minimum helps keep your running costs down during idle
periods, but means that fewer instances might be immediately
available to respond to a sudden load spike.
A high minimum allows you to prime the application for rapid
spikes in request load. App Engine keeps the minimum
number of instances running to serve incoming requests. You
are charged for the number of instances specified, whether or
not they are handling requests. For this feature to function
properly, you must make sure that
warmup requests are enabled and that your application
handles warmup requests.
If you set a minimum number of idle instances, pending latency
will have less effect on your application's performance.
Because App Engine keeps idle instances in reserve, it
is unlikely that requests will enter the pending queue except
in exceptionally high load spikes. You will need to test your
application and expected traffic volume to determine the ideal
number of instances to keep in reserve.
min_pending_latency
The minimum amount of time that App Engine should allow a request
to wait in the pending queue before starting a new instance to
handle it. When this threshold is reached, it is a signal to scale
down, and results in a decrease in the number of instances. The
default value is 30ms.
A low minimum means requests must spend less time in the pending
queue when all existing instances are active. This improves
performance but increases the cost of running your application.
A high minimum means requests will remain pending longer if all
existing instances are active. This lowers running costs but
increases the time users must wait for their requests to be
served.
Example
service: my_service
runtime: go
api_version: go1
instance_class: F2
automatic_scaling:
min_idle_instances: 5
max_idle_instances: automatic # default value
min_pending_latency: 30ms # default value
max_pending_latency: automatic
max_concurrent_requests: 50
basic_scaling
Optional.
The basic_scaling element sets the number of instances
for a service.
This element can contain the following elements:
idle_timeout
Optional. The instance will be shut down this amount of time after
receiving its last request. The default is 5 minutes
(5m).
max_instances
Required. The maximum number of instances for App Engine to
create for this service version. This is useful to limit the costs
of a service.
The expiration time will be sent in the Cache-Control and Expires HTTP
response headers, and therefore, the files are likely to be cached by the user's
browser, as well as by intermediate caching proxy servers such as Internet
Service Providers. After a file is transmitted with a given expiration time,
there is generally no way to clear it out of intermediate caches, even if
the user clears their own browser cache. Re-deploying a new version of the app
will not reset any caches. Therefore, if you ever plan to modify a static
file, it should have a short (less than one hour) expiration time. In most
cases, the default 10-minute expiration time is appropriate.
Оцените, насколько информация на этой странице была вам полезна:
