Organizing Configuration Files

Use the following document to understand how to structure the services and
related resources of your app for App Engine.

Directory structure

Each version of your App Engine service is defined in an
app.yaml
configuration file. For simple apps, the minimum requirement for deployment is
to define the app.yaml file. The app.yaml file acts as a deployment
descriptor and defines the scaling type and the
CPU, disk, and memory resources for a specific version of a
service. If you are deploying several versions of a service, you can create
multiple YAML files in the same directory to represent the configuration for
each of your versions.
For each service, you can create separate directories in the root of your app
when you are developing locally. If you host your app out of a version control
system (VCS), for example GitHub, you can also structure your app to use
separate directories in a repository, or use separate repositories for each
service. Each directory or repository should represent a single service and
contain that service's app.yaml file along with the associated source code.

You have the option of specifying a unique name for each of your service's
app.yaml file. For example, you can name a configuration file after your
service, or use unique names to represent each version of that particular
service, like service1.yaml or app.flexible.yaml.

The other optional configuration files should
reside in the root directory or repository of the
default service of your app. These optional
configuration files apply app-wide settings that are not specific to a
particular service, including the dispatch.yaml,
index.yaml and cron.yaml files.

Examples

The following example demonstrates what an app with three services might look
like if you are developing your app locally. The optional dispatch.yaml has
been added to that app in the root directory. Also in the root are three
directories for each of the app's services. The subdirectory for service1
includes the source and configuration files for that service. Similarly, both
service2 and service3 are in separate directories, which contain each
service's files, although service3 includes two versions of the YAML
configuration file:

For a single
service app, that app will only include the
default service and all the files can live in the same
directory, at the root of that
app. In the following example, the possible structure of a single service
app is demonstrated and includes the optional dispatch.yaml configuration file
and two configuration files that represent different versions of that service,
service1.yaml and service2.yaml:

Design considerations for instance uptime

Hardware or software failures that cause early termination or frequent instance
restarts can occur without warning and can take considerable time to resolve.
Your application should be able to handle such failures.

Here are some good strategies for avoiding downtime due to instance restarts:

Reduce the amount of time it takes for your instances restart or for new ones
to start.

For long-running computations, periodically create checkpoints so that you
can resume from that state.

Your app should be "stateless" so that nothing is stored on the instance.

The default service

Every App Engine application includes a default service. You must
deploy the initial version of your app to the default service before you can
create and deploy additional services to your app.

The default service can be optionally specified
in the app.yaml with the setting
service: default.

Requests sent to your app using your GCP project are sent to the
default service, for example, https://[PROJECT_ID].appspot.com. To learn
more about targeting your other services, see Communicating Between
Services.

Optional configuration files

The following configuration files control optional features that apply to all of
the services in an individual app. See the following topics for details about
each of the optional features:

You can also choose how you want to serve your static content. You can serve
your app's static content directly from that app in App Engine, host
your static content on a GCP option like
Cloud Storage, or use a third-party content delivery network (CDN).
For more information about serving static content, see Serving Static
Files.