NOTICE: The Azure Service Fabric provider for Traefik is maintained at https://github.com/containous/traefik-extra-service-fabric. This repository was created before the work was merged as a way to track issues and document the provider. There is still some useful information, demos and tools in this repository which will continue to exist but we will not be actively maintaining this content. Therefore, if you are having trouble with the provider, please open an issue on the Containous repository or reach out to the Containous team directly on their Slack. If you want to maintain your own fork of this repository please feel free to in line with the LICENSE.
Disclaimer: Azure Service Fabric integration was added to Træfik in version 1.5 - please use this version or later.
Warning: Work is currently underway in Træfik to standardize label names between providers. In future releases labels will change, for example:
traefik.expose->traefik.enable. See PR16 to follow the work.
Running Træfik on Azure Service Fabric
What is Træfik?
Træfik (pronounced like traffic) is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. It supports several backends (Docker, Swarm mode, Kubernetes, Marathon, Consul, Etcd, Rancher, Amazon ECS, and a lot more) to manage its configuration automatically and dynamically. For more information, visit the Træfik homepage
What is Azure Service Fabric?
Azure Service Fabric is a distributed systems platform that makes it easy to package, deploy, and manage scalable and reliable microservices and containers. For more information, visit the Azure Service Fabric homepage
Why run Træfik on Azure Service Fabric?
Integrating Træfik and Azure Service Fabric allows you to configure much more advanced, yet flexible, ingress routing scenarios for your Service Fabric hosted services and applications. You get all the benefits of using Træfik to configure your routing whilst also getting the benefits of Service Fabric's packaging model.
Deploying Traefik to Azure Service Fabric
Azure Service Fabric supports many different methods of deploying applications. Please select the most appropriate from the list below.
- Windows using Visual Studio
- Windows, MacOS and Linux using sfctl
- Windows, MacOS and Linux using docker [Not recommended currently]
Releases
The Azure Service Fabric integration ships as part of Træfik v1.5 or greater, so for stable builds please use the official Træfik releases page. The releases on this repository are for experimental features that may or may not be included in the upstream Træfik tree at a later date.
Exposing a Azure Service Fabric Application
Træfik uses the concept of labels to configure how services are exposed.
Labels allow you to define additional metadata for your services which Træfik can use to configure itself dynamically.
Adding Service labels
In order to assign labels for your service, you can add Extensions to your service's ServiceManifest.xml. Træfik will select any labels prefixed with traefik. Here is an example of using extensions to add Træfik labels:
<StatelessServiceType ServiceTypeName="WebServiceType">
<Extensions>
<Extension Name="Traefik">
<Labels xmlns="http://schemas.microsoft.com/2015/03/fabact-no-schema">
<Label Key="traefik.frontend.rule.example">PathPrefixStrip: /a/path/to/strip</Label>
<Label Key="traefik.expose">true</Label>
<Label Key="traefik.frontend.passHostHeader">true</Label>
</Labels>
</Extension>
</Extensions>
</StatelessServiceType>Warning: In Træfik v1.6 label names have been standardized between providers. If you are using v1.6 please update the sample as follows:
traefik.expose->traefik.enable. Additionally backends will no longer be created for services which aren't enabled.
Note: The Service Fabric service requires the UriScheme attrbute set in its Endpoint Resource entry in order to be discoverable: Example
<Resources> <Endpoints> <Endpoint Protocol="http" Name="ServiceEndpoint" Type="Input" Port="9001" UriScheme="http" /> </Endpoints> </Resources>
Note: Stateless Services and Guest Executables are fully supported with experimental support for Stateful Services. The discussion around more complete support for Stateful Service is ongoing. See Issue 45 to follow the progress.
Dynamically updating Service labels
Once you've deployed your service with some default labels, you may need to change the way Træfik is routing requests without redeploying. You can overwrite and add new labels to a named service using Service Fabric's Property Management API. Træfik will then pick up these new/updated labels and reconfigure itself.
Setting a label dynamically using curl
curl -X PUT \
'http://localhost:19080/Names/GettingStartedApplication2/WebService/$/GetProperty?api-version=6.0&IncludeValues=true' \
-d '{
"PropertyName": "traefik.frontend.rule.default",
"Value": {
"Kind": "String",
"Data": "PathPrefixStrip: /a/path/to/strip"
},
"CustomTypeId": "LabelType"
}'WARNING: The json provided in the body is case sensitive.
Setting a label dynamically using sfctl
It is also possible to use sfctl to operate with properties without make raw HTTP requests.
sfctl property put --name-id "GettingStartedApplication/WebService" --property-name "traefik.frontend.rule.default" --value "{\"Kind\": \"String\",\"Data\": \"PathPrefixStrip: /a/path/to/strip\"}"The command above is current as of sftcl v4.0.0.
Available Labels
The current list of available labels is documented here. This is subject to change as we expand our capabilities.
Debugging
Both services will output logs to stdout and stderr. To enable these logs uncomment the ConsoleRedirection line in both ServiceManifest.xml files.
<ExeHost>
<Program>traefik-appinsights-watchdog.exe</Program>
<Arguments>--appinsightskey=__YOUKEYHERE__ --watchdogtestserverport=29001 --pollintervalsec=60 --debug=true</Arguments>
<WorkingFolder>CodePackage</WorkingFolder>
<!-- <ConsoleRedirection FileRetentionCount="5" FileMaxSizeInKb="2048" /> -->
</ExeHost>Once deployed, logs will be stored in the nodes Service Fabric folder. This will be similar to D:\SvcFab\_App\TraefikType_App1\log but may vary depending on your configuration.
Common Issues
- Azure Service Fabric Provider not shown in Traefik Dashboard: Check you have correctly configured the certificates and clustermanagementurl
- No events showing in App Insights for Traefik: Check you have uncommented the default services section and double check your instrumentation key is correct
Custom Templates
For advanced users only
If the default configuration the Azure Service Fabric Træfik provider builds is not sufficient for your needs, you can write a custom template that the provider will use instead. Documentation on how to write a custom template is available here. Your custom template will need to be added to either your application's Code or Config folders and the relative URL provided in the traefik.toml configuration.
The functions available for you to use in your custom template are documented here.
How does Træfik on Azure Service Fabric work?
Træfik is hosted as a Azure Service Fabric Guest Executable. Træfik has a built-in Azure Service Fabric provider which will query the Service Fabric management API to discover what services are currently being hosted in the cluster (referred to as backends). The provider then maps routing rules (known as frontends) to these service instances (referred to as backends). Ingress flows in via entrypoints (http, https, etc.), frontends are then applied to match and modify each requests before load balancing across the associated backends. The provider will take into account the Health and Status of each of the services to ensure requests are only routed to healthy service instances.
To learn more about how Træfik works and how you can configure is, please see their documentation.
Updating Traefik
If you would like to update the Træfik binary, certs or traefik.toml file. You can use Azure Service Fabric's built in 'rolling updates' as you would with any other application package.
Multi-Environment support and automated management of certificates
One of the issues that comes up during the setup is the need to package and deploy certificates along with Træfik. This can prove difficult if
- You have your applications getting deployed to multiple environments using different certificates
- Your build system does not have access to certificates
To solve these issues easily you can use PreConfiguratorForTraefikOnServiceFabric to automate fetching of certificates from LocalMachine or KeyVault and process them for Træfik to use. This eliminates the need to package any certificate along with Træfik.
Contributing
See our Contributing guide
Related Repositories
- Traefik Azure Service Fabric provider development: https://github.com/containous/traefik-extra-service-fabric
- Go SF Management SDK: https://github.com/jjcollinge/servicefabric
- sfctl for property management: microsoft/service-fabric-cli#53
- Application Insights Watchdog: https://github.com/lawrencegripper/traefik-appinsights-watchdog
- Pre-configurator for multi-environment deploments: https://github.com/RamjotSingh/PreConfiguratorForTraefikOnServiceFabric